Guide Topbar layout

Style Hierarchy

Use the earliest truthful hook:
HTML, state, roles, variants.
Layout helpers, tokens, then custom CSS.

Open Docs Open Forms Decision Matrix
First choice HTML Semantic
Second choice ARIA State
Last choice CSS Custom

Default Order

Use this order when deciding how to get a platinum.css style.

Priority Use When Example
1 Semantic HTML The element already means the thing you are building. <button>, <article>, <details>
2 Native or ARIA state The UI state must be exposed to assistive technology. disabled, aria-current, aria-invalid
3 ARIA role No native element maps cleanly to the widget pattern. role="tab", role="listbox", role="progressbar"
4 Variant class or data attribute You are choosing a visual variant, not describing state. class="secondary", data-variant="warning"
5 Layout helper You need arrangement, spacing, or a page shell. layout-sidebar, grid, stack, cluster
6 Theme token The style should change everywhere consistently. --primary, --button-face, --radius-3
7 Custom CSS The project has a new pattern outside the library. .lesson-card, .billing-summary

1. Semantic HTML

Start with the element that carries the meaning. The stylesheet handles the baseline chrome.

Document Structure

Articles, headings, paragraphs, lists, tables, blockquotes, code, details, and buttons are styled directly.

Native disclosure

No class is needed for this block to look like a disclosure control.

Native Controls

<article>
  <header>
    <h2>Lesson Notes</h2>
  </header>
  <p>Use document elements first.</p>
  <details open>
    <summary>Native disclosure</summary>
    <p>No class needed.</p>
  </details>
</article>

<form>
  <label for="title">Title</label>
  <input id="title" name="title">
  <button>Save</button>
</form>

2. Native and ARIA State

State should live in the DOM attribute that describes the actual state.

Controls

Use lowercase letters and dashes.

Navigation and Data

Name Status
Unit one Ready
Unit two Review 
<button aria-pressed="true">Pressed</button>
<button aria-busy="true">Saving</button>
<button disabled>Disabled</button>

<input aria-invalid="true" aria-describedby="handle-error">
<small id="handle-error" data-variant="danger">Use lowercase letters and dashes.</small>

<a href="/docs" aria-current="page">Docs</a>
<th aria-sort="ascending">Name</th>

3. Roles for Composite Widgets

Use roles when a real widget pattern needs script-managed state and keyboard behavior.

Tabs

Overview

Static link tabs can use aria-current. Scripted ARIA tabs can use role="tab" with aria-selected.

Selection and Values

  • Lecture notes
  • Lab rubric
<button role="tab" aria-selected="true" aria-controls="overview">Overview</button>
<section id="overview" role="tabpanel">...</section>

<ul role="listbox" aria-multiselectable="true">
  <li role="option" aria-selected="true" tabindex="0">Lecture notes</li>
</ul>

<div role="progressbar" aria-valuenow="72" style="--value: 72%"></div>

4. Classes and Data Attributes

Use these for visual variants, composition patterns, and explicit opt-ins.

Class Variants

Anchor Button

Data Variants

Default notice.
Informational notice.
Warning notice.
Danger alert.
<button>Primary</button>
<button class="secondary">Secondary</button>
<a href="/download" class="button">Anchor Button</a>

<div class="notice" data-variant="warning">Warning notice.</div>
<span class="badge" data-variant="info">Info</span>

5. Layout Helpers

Use helper classes for arrangement. They should not replace semantic structure.

Composition

Alpha Beta Gamma
One Two Three

Page Shells

layout-topbar
Top navigation with centered document flow.
layout-sidebar
Top navigation, sidebar navigation, and main content.
layout-scroll
Narrow vertical flow for focused pages and forms.
<body class="layout-sidebar">
  <header>...</header>
  <aside class="sidebar">...</aside>
  <main>...</main>
</body>

<div class="stack">
  <div class="cluster">...</div>
  <div class="grid">...</div>
</div>

6. Theme Tokens

Override tokens when the change should apply consistently across components.

Scoped Token Preview

This preview overrides a few tokens on the container, so descendants inherit the change.

Scoped
Tokens inherit through normal CSS.
:root {
  --primary: #245c8f;
  --primary-hover: #16436d;
  --button-face-hover: #e7eef8;
  --radius-3: 8px;
}

7. Custom CSS Last

Add project CSS when the library does not contain the concept. Keep the new class narrow and semantic.

Use a custom class for a real project pattern, not for a state that already has an HTML or ARIA attribute.
Prefer Instead of Reason
aria-current="page" class="active" Current location is real state.
aria-invalid="true" class="error" Validation state should be exposed.
data-variant="warning" class="yellow" The intent matters more than the color.
--primary Overriding every selected component Tokens keep the system coherent. 
.billing-summary {
  display: grid;
  gap: var(--space-3);
  grid-template-columns: minmax(0, 1fr) max-content;
}

.billing-summary [data-total] {
  font-family: var(--font-heading);
}