- **Always use and maintain this import syntax** in the app.css file for projects generated with `phx.new`

- **Never** use `@apply` when writing raw css

- **There is exactly one component system: vendored Basecoat plus OpenAgents style pack.** Basecoat lives in `assets/vendor/basecoat/components/` and carries structure (display, padding, min-height); `assets/css/openagents.css` carries OpenAgents' identity (motion tokens, radius scale, colour, the notched variant, corner frames) and must stay the last import so its declarations win.

- **There is exactly one component system: vendored Basecoat plus OpenAgents style pack.** Basecoat lives in `assets/vendor/basecoat/components/` and carries structure (display, padding, min-height); `assets/css/openagents.css` carries OpenAgents' identity (motion tokens, radius scale, color, the notched variant, corner frames) and must stay the last import so its declarations win.

  - **Reach for `OpenAgentsWeb.UI` first.** It wraps that CSS in 22 ready primitives — `button/1`, `card/1`, `badge/1`, `alert/1`, `input/1`, `textarea/1`, `label/1`, `field/1`, `header/1`, `table/1`, `list/1`, `avatar/1`, `menu/1`, `empty/1`, `kbd/1`, and the rest. Fall back to hand-written classes only when no primitive covers the shape.

  - **Variants are data attributes, not classes.** A control is `class="btn"` plus `data-variant="primary"` / `data-size="sm"` / `data-tone="danger"`. Never invent `btn-primary`-style variant classes; they defeat the whole point of the split.

  - **Never add a second component library — DaisyUI above all.** DaisyUI was removed deliberately. It emitted flat `.btn` rules (setting background, colour, border) from a cascade layer that outranked every `.btn[data-variant=…]` in `openagents.css`, so all eight UI button variants rendered identically on staging. Any library with the same shape will do the same thing again.

  - **Never add a second component library — DaisyUI above all.** DaisyUI was removed deliberately. It emitted flat `.btn` rules (setting background, color, border) from a cascade layer that outranked every `.btn[data-variant=…]` in `openagents.css`, so all eight UI button variants rendered identically on staging. Any library with the same shape will do the same thing again.

  - **Import Basecoat components individually**, one `@import "../vendor/basecoat/components/<name>.css"` per component a surface actually uses. Component CSS lands in `@layer components` and ships whether or not the class appears in markup, so the list is a budget. **Never** import `basecoat.css`, `basecoat-base.css`, or `basecoat-components.css` — each pulls in all 39 components at once.

  - The palette is the token ladder at the top of `app.css` (`--ink-void` / `--ink-surface` / `--ink-raised`, the text and line tiers, and the four semantic colours). It is dark-only. Use the Basecoat utility names built on it — `bg-background`, `bg-card`, `text-foreground`, `text-muted-foreground`, and `border-border`. The retired compatibility aliases no longer exist

  - The palette is the two owned token ladders in `assets/css/openagents.css`. The interface supports only light and dark palettes; the system preference selects between them and is not a third palette. Use the Basecoat utility names built on these tokens — `bg-background`, `bg-card`, `text-foreground`, `text-muted-foreground`, and `border-border`. The retired compatibility aliases no longer exist

- Add custom Tailwind only when the design is unique to OpenAgents and no primitive fits.

- Out of the box **only the app.js and app.css bundles are supported**

  - You cannot reference an external vendor'd script `src` or link `href` in the layouts

  - You must import the vendor deps into app.js and app.css to use them

  - **Never write inline <script>custom js</script> tags within templates**

  - **Never write inline `<script>` tags within templates.** The only exception is the synchronous, content-free theme bootstrap in `root.html.heex`, which must run before the first stylesheet paint. Put every other client behavior in `app.js` or a colocated LiveView hook

### UI and UX design guidelines

popover API, so the identity control works without custom client-side script.

Where Basecoat has no equivalent, the primitive wraps the browser's own control

rather than reimplementing it: `audio_player/1` is a native `<audio controls>`

in a OpenAgents-styled box, keyboard operable and announced by the user agent, and it

requires an accessible name because a page of recordings is otherwise a page of

identically announced players.

The shared corner radius, the self-hosted Geist faces, the single dark theme,

and the reserved semantic color meanings hold across every component. Depth is

limited to the sanctioned lift, halo, and state-ring tokens.

in an OpenAgents-styled box, keyboard operable and announced by the user agent,

and it requires an accessible name because a page of recordings is otherwise a

page of identically announced players.

The shared corner radius, the self-hosted Geist faces, exactly two owned themes,

and the reserved semantic color meanings hold across every component. The

system preference selects light or dark through `prefers-color-scheme`; it does

not introduce a third palette. Depth is limited to the sanctioned lift, halo,

and state-ring tokens.

Adopting an additional Basecoat component requires a

`docs/component-library.md` change and an explicit per-component import. The

application exposes no light/system theme control while the palette is

dark-only. Apps SDK UI glyphs are preferred; the pinned Heroicons fallback has

an explicit inventory and no current product call sites.

application exposes one system, light, and dark preference control. A

synchronous, content-free bootstrap applies the stored choice before first

paint and synchronizes changes across tabs. Apps SDK UI glyphs are preferred;

the pinned Heroicons fallback has an explicit inventory and no current product

call sites.

Evidence: `assets/vendor/basecoat/README.md`, `assets/css/openagents.css`,

`priv/static/fonts`, `OpenAgentsWeb.UI`, `OpenAgentsWeb.ComponentCatalog`,

`OpenAgentsWeb.UITest`, `OpenAgentsWeb.UIGalleryLiveTest`,

`test/openagents_web/component_catalog_test.exs`,

`test/openagents_web/icon_affordances_test.exs`, and

`test/openagents_web/icon_affordances_test.exs`,

`test/openagents_web/live/components_live_test.exs`, and

`assets/test/css_contract_test.mjs`.

### LEADERBOARD-001 — The public board publishes one bounded projection

  Tailwind and proves that exactly two owned themes and the system fallback

  survive, Basecoat geometry precedes the OpenAgents style pack, and all eight

  governed button variants survive the cascade.

- Reconciled `AGENTS.md`, UI-003, and the component guide with the later light

  palette. The documentation check now refuses the superseded dark-only claims

  in active contracts, and the component test enumerates the system, light, and

  dark controls without treating the system preference as a third palette.

- Migrated current glyph uses to the preferred vendored Apps SDK set. Retained

  Heroicons only as the owner-approved second tier, pinned it to immutable

  revision `0435d4ca364a608cc75e2f8683d374e55abbae26`, and recorded an empty

| Component | Purpose |

| --- | --- |

| `button/1`, `text_button/1` | Boxed, link, chip, destructive, and primary actions |

| `input/1`, `textarea/1`, `label/1`, `field/1` | Form-aware controls and labelled groups |

| `input/1`, `textarea/1`, `label/1`, `field/1` | Form-aware controls and labeled groups |

| `header/1`, `table/1`, `list/1` | Page headings and structured data |

| `alert/1`, `badge/1`, `status_indicator/1` | Explicit feedback and semantic state |

| `card/1`, `frame/1` | Bounded content and decorative framing |

`OpenAgentsWeb.Layouts` owns `app/1`, `flash_group/1`, `command_bar/1`,

and `account_control/1`. Product templates begin with `Layouts.app` and never

render `flash_group/1` directly. The staging palette is deliberately dark-only,

so the application exposes no theme control or browser theme state.

render `flash_group/1` directly. The command bar exposes one system, light, and

dark preference control over exactly two owned palettes. The system choice

stores no override and follows `prefers-color-scheme`. The synchronous theme

bootstrap in `root.html.heex` applies an explicit choice before the first paint

and synchronizes it across tabs.

## Specialized components

The compiled CSS contract test proves that Basecoat geometry precedes the

OpenAgents style pack, every supported button variant survives compilation, no

retired palette alias survives, and no theme selector enters the bundle.

retired palette alias survives, both owned themes compile, the operating-system

fallback compiles, and no third theme selector enters the bundle.

See [the UI roadmap](issues-projects-ui-roadmap.md),

[ADR 0005](decisions/0005-use-basecoat-and-one-component-system.md), and the

    {~r{/home/[A-Za-z0-9._-]+/(?:work|code)(?:/|\b)}, "Linux developer path"}

  ]

  @theme_contract_files ["AGENTS.md", "INVARIANTS.md", "docs/component-library.md"]

  @retired_theme_claims [

    {~r/\bdark-only\b/i, "retired dark-only theme claim"},

    {~r/\bsingle dark theme\b/i, "retired single-theme claim"},

    {~r/\bno theme selector enters the bundle\b/i, "retired selector-free theme claim"}

  ]

  def run do

    errors =

      []

      |> check_markdown_links()

      |> check_current_language()

      |> check_theme_contract()

      |> check_invariants()

    case Enum.reverse(errors) do

    end)

  end

  defp check_theme_contract(errors) do

    Enum.reduce(@theme_contract_files, errors, fn file, acc ->

      scan_terms(acc, file, File.read!(file), @retired_theme_claims)

    end)

  end

  defp check_invariants(errors) do

    content = File.read!("INVARIANTS.md")

    sections = invariant_sections(content)

    refute has_element?(view, ~s{a[href="/components/theme-toggle"]})

  end

  test "the command bar exposes exactly the governed theme preferences" do

    document =

      OpenAgentsWeb.Layouts.theme_toggle(%{})

      |> rendered_to_string()

      |> LazyHTML.from_fragment()

    assert document

           |> LazyHTML.query(~s{.theme-toggle[role="group"][aria-label="Color theme"]})

           |> LazyHTML.to_tree() != []

    assert document

           |> LazyHTML.query(

             ~s{button[data-theme-option="system"][aria-label="Match system theme"]}

           )

           |> LazyHTML.to_tree() != []

    assert document

           |> LazyHTML.query(~s{button[data-theme-option="light"][aria-label="Light theme"]})

           |> LazyHTML.to_tree() != []

    assert document

           |> LazyHTML.query(~s{button[data-theme-option="dark"][aria-label="Dark theme"]})

           |> LazyHTML.to_tree() != []

    assert document

           |> LazyHTML.query(~s{button[data-theme-option]})

           |> LazyHTML.to_tree()

           |> length() == 3

  end

end