# Needle Brand System

> Needle interfaces are calm, precise, compact, and easy to work in. Use a soft green stage, crisp white work surfaces, dark readable text, restrained shadows, and green accents that support the task.

## Files

- brand.json: Full brand specification — colors, typography, logos, principles, dimensions, and page types.
- brand-recipes.json: UI patterns such as header pill, card, footer, and code block.
- brand.css: CSS file with @font-face declarations, semantic tokens under :root{}, grouped component anatomy variables such as `--header-tool-row-*`, `--layout-workbench-shell-*`, `--control-segmented-track-*`, `--control-slider-*`, `--tag-*`, and `--user-profile-*`, plus classes such as `.header-tool`, `.segmented-control`, `.pane`, `.stage`, `.property-row`, `.check-row`, `.color-row`, `.tag`, `.user-profile`, and `.footer-area`. Include it with <link rel="stylesheet" href="brand.css" />.

## Conventions

CSS variables follow semantic role paths. Join groups with hyphens and convert camelCase to kebab-case. Example: palette.roles.surface.pageElevated → --surface-page-elevated. Typography roles use the same pattern with a type- prefix.

brand-recipes.json lists the UI patterns. Each pattern names the roles it uses and includes the build instruction in `llmInstruction`.

Font files are relative to brand.css. Every family with a `file` field gets an @font-face in brand.css. If `fontStyle` is set, the @font-face uses it.

Reuse the classes from brand.css before writing custom CSS: `.header-tool`, `.header-tool-leading`, `.header-tool-title-group`, `.header-tool-actions`, `.header-tool-status`, `.header-tool-button`, `.status-strip`, `.status-strip-item`, `.status-strip-label`, `.workbench-shell`, `.workbench-grid`, `.stage`, `.stage-toolbar`, `.stage-canvas`, `.stage-footer`, `.pane`, `.pane-head`, `.pane-body`, `.segmented-control`, `.property-list`, `.property-row`, `.property-row-head`, `.check-row`, `.color-row`, `.color-field`, `.color-field-button`, `.color-popover`, `.tag-list`, `.tag`, `.tag-segmented`, `.tag-segmented-label`, `.tag-segmented-meta`, `.list`, `.list-row`, `.user-profile`, `.user-profile-logo`, `.user-profile-identity`, `.user-profile-avatar`, `.user-profile-card`, `.user-profile-card-row`, `.user-profile-card-actions`, `.header-pill-shell`, `.header-pill`, `.header-pill-brand`, `.header-pill-nav`, `.header-pill-actions`, `.header-pill-dropdown`, `.footer-area`, `.footer-area-main`, `.footer-area-brand`, and `.footer-area-column`. Matching `--*-*` variables follow the same structure.

## Shell Selection

Choose the information architecture first, then the shell:
- one dominant work surface with dense operational chrome -> `header-tool`
- browsing, docs, marketing, or lighter management -> `header-pill`
- use `footer-area` only when the page genuinely ends like a website
- dense operational pages do not end with a marketing footer

## Shell HTML

Canonical shells:

`workbench`
```html
<div class="workbench-shell">
  <header class="header-tool">...</header>
  <!-- optional status-strip -->
  <main class="workbench-grid">
    <!-- choose one dominant surface -->
    <section class="stage">...</section>
    <!-- add one or two panes only if the task needs them -->
    <aside class="pane">...</aside>
  </main>
</div>
```

`management`
```html
<div class="management-page">
  <div class="header-pill-shell">
    <header class="header-pill">...</header>
  </div>
  <main>...</main>
  <!-- optional footer-area when the page ends like a website -->
</div>
```

`docs`
```html
<div class="docs-page">
  <div class="header-pill-shell">
    <header class="header-pill">...</header>
  </div>
  <main>...</main>
  <footer class="footer-area">...</footer>
</div>
```

`marketing`
```html
<div class="marketing-page">
  <div class="header-pill-shell">
    <header class="header-pill">...</header>
  </div>
  <main>...</main>
  <footer class="footer-area">...</footer>
</div>
```

## Component HTML

Reuse these classes from a local copy of brand.css:

`header-tool`
```html
<header class="header-tool">
  <div class="header-tool-leading">
    <img src="./logos/logo_needle_black_no_padding.svg" alt="Needle" />
    <div class="header-tool-title-group">
      <strong>Current Tool</strong>
      <span>current file / current context</span>
    </div>
  </div>
  <div class="segmented-control" role="tablist" aria-label="Workspace mode">
    <button aria-selected="true">Primary</button>
    <button>Secondary</button>
    <button>Export</button>
  </div>
  <div class="header-tool-actions">
    <span class="header-tool-status">Ready</span>
    <button class="header-tool-button">Save</button>
  </div>
</header>
```

`segmented-control`
```html
<div class="segmented-control" role="tablist" aria-label="View mode">
  <button aria-selected="true">Primary</button>
  <button>Secondary</button>
  <button>Raw</button>
</div>
```

`property-row`
```html
<div class="property-row">
  <div class="property-row-head">
    <label for="exposure">Exposure</label>
    <output for="exposure">1.10</output>
  </div>
  <input id="exposure" type="range" min="0" max="100" value="24" />
</div>
```

`check-row`
```html
<div class="check-row">
  <label for="volumetric">Enabled</label>
  <input id="volumetric" type="checkbox" checked />
</div>
```

`color-row`
```html
<div class="color-row">
  <label for="key-tint">Tint</label>
  <div class="color-field">
    <button class="color-field-button" type="button">
      <span class="color-swatch" style="background:#F6DDBB"></span>
      <span>#F6DDBB</span>
    </button>
    <div class="color-popover">
      <input id="key-tint" type="color" value="#F6DDBB" />
      <input class="color-input" type="text" value="#F6DDBB" />
      <input type="range" min="0" max="100" value="72" />
    </div>
  </div>
</div>
```

`user-profile`
```html
<button class="user-profile" type="button">
  <img class="user-profile-logo" src="./logos/logo_needle_black_no_padding.svg" alt="Needle" />
  <span class="user-profile-identity">
    <strong class="user-profile-name">Felix Herbst</strong>
    <span class="user-profile-meta">Needle Test</span>
  </span>
  <span class="user-profile-avatar">FH</span>
</button>
```
Use the same segmented control everywhere. Use property, check, and color rows directly in technical panes. Use user-profile for account identity, not page titles. Do not box controls individually.

## Build Order

- Start with the primary task, object, and surface.
- Choose a page type after the information architecture is clear.
- Ship a local copy of `brand.css`, or copy the rules you need into the app stylesheet.
- Copy the real logo assets into the app bundle.
- Reuse the core classes from `brand.css` for `header-tool`, `segmented-control`, `pane`, `stage`, `property-row`, `check-row`, `color-row`, `tag`, and `user-profile` before adding page-specific CSS.
- Use `header-tool` for dense operational pages. Use `header-pill` for marketing, docs, browsing, and lighter management pages.
- Use the footer only on marketing and docs pages. Workbench shells do not end with a marketing footer in the first viewport.
- Use a stage only when the user needs space to inspect or manipulate a result.
- Keep presets and controls close to the thing they affect.
- Follow the grouped component structure in `brand.css` when building headers, workbench shells, stage surfaces, panes, segmented controls, property rows, sliders, enum switches, and boolean rows.
- Use the live branding site only as a reference while generating. Do not ship a page that links to localhost brand files at runtime.
- Use compact operational chrome for tools: short titles, inline status, one dominant work surface, and compact side panels.
- Put long explanations in docs, onboarding, help drawers, or empty states instead of persistent tool chrome.

## Hard Rules

Hard rules:
- The finished page is self-contained.
- Use one header family per page.
- Dense operational pages use `header-tool`; browsing, docs, marketing, and lighter management pages use `header-pill`.
- If you copied brand.css, do not redeclare `--surface-*`, `--text-*`, `--accent-*`, or `--border-*`.
- Reuse the canonical segmented control, property rows, check rows, and color rows.
- Do not append `footer-area` to dense operational pages.

## Common Patterns

Common patterns:
- A three-pane workbench is common when a visual result needs a large stage.
- A two-column layout is common when the task is result plus settings.
- One continuous inspector is common when the task is mostly configuration or review.
- Management pages often use rows, tables, or compact cards instead of a stage.

## Component Anatomy Variables

- `--header-tool-row-*`, `--header-tool-leading-*`, `--header-tool-title-group-*`, `--header-tool-actions-*`: Compact operational header for dense viewers, editors, inspectors, and focused studios. Hierarchy: `header-tool > leading + modes + actions`.
- `--status-strip-*`, `--status-strip-item-*`: Optional inline operational readout for runtime, counts, warnings, and selection. Hierarchy: `status-strip > status-item[]`.
- `--layout-workbench-shell-*`, `--layout-workbench-grid-*`: Viewport-first shell for tools with one dominant stage and compact side panes. Hierarchy: `workbench-shell > header-tool + optional status-strip + workbench-grid`.
- `--surface-stage-*`: Central work surface with stage toolbar, canvas, and footer metadata. Hierarchy: `stage > stage-toolbar + stage-canvas + stage-footer`.
- `--surface-stage-toolbar-*`: Compact row at the top of the stage for mode switches and direct stage actions. Hierarchy: `stage-toolbar > controls + meta`.
- `--surface-stage-canvas-*`: Neutral or dark central canvas for the actual visual work. Hierarchy: `stage-canvas > scene`.
- `--surface-stage-footer-*`: Compact bottom row for metrics, selection facts, and stage-level summaries. Hierarchy: `stage-footer > label + metrics`.
- `--pane-*`, `--pane-head-*`, `--pane-body-*`: Pane shell plus its head/body split for inspectors and side panels. Hierarchy: `pane > pane-head + pane-body`.
- `--control-segmented-track-*`, `--control-segmented-segment-*`: Joined viewer-style segment row with one border system shared across the whole control. Hierarchy: `segmented-track > segment[]`.
- `--control-property-list-*`, `--control-property-row-*`, `--control-property-row-head-*`, `--control-property-row-label-*`, `--control-property-row-value-*`: Continuous property pane plus the label/value row anatomy used before sliders, enums, and checks. Hierarchy: `property-list > property-row > property-row-head`.
- `--control-slider-track-*`, `--control-slider-thumb-*`: Real range input styling for technical rows. Hierarchy: `property-row > input[type=range]`.
- `--control-check-row-*`, `--control-check-box-*`: Compact boolean row with a technical check box, not a phone-style switch. Hierarchy: `check-row > label + input[type=checkbox]`.
- `--control-color-row-*`, `--control-color-swatch-*`, `--control-color-input-*`, `--control-color-popover-*`: One-line color row with a field trigger; detailed color and alpha controls live in a popover. Hierarchy: `color-row > label + color-field > color-field-button + color-popover`.
- `--tag-*`: Compact status chip for viewer and cloud surfaces, including optional split metadata. Hierarchy: `tag-list > tag[] or tag-segmented > tag-segmented-label + tag-segmented-meta`.
- `--list-row-*`: Dense rows for presets, uploads, warnings, and asset lists. Hierarchy: `list > list-row[]`.
- `--user-profile-shell-*`, `--user-profile-avatar-*`, `--user-profile-card-*`: Cloud-style account identity for header pills, account menus, and profile summary panels. Hierarchy: `user-profile > logo + identity + avatar; user-profile-card > head + rows + actions`.
- `--header-pill-shell-*`, `--header-pill-nav-*`, `--header-pill-actions-*`: Floating marketing/docs header with brand, navigation, and CTA cluster. Hierarchy: `header-pill-shell > brand + nav + actions`.
- `--footer-marketing-shell-*`, `--footer-marketing-main-*`, `--footer-marketing-column-*`: Marketing/docs footer with brand summary, columns, and one legal row. Hierarchy: `footer-marketing-shell > footer-marketing-main + footer-marketing-legal`.

## Content Economy

- Keep tool titles short.
- In workbench headers, the tool name and current context read before the brand.
- Pane headers should not restate their own role.
- Helper text is short and local.
- Long explanation belongs in docs, onboarding, help, or empty states.

## Anti-Patterns

- Do not use a hero header in a workbench.
- Do not use `header-pill` inside dense editors, inspectors, or technical panes.
- Do not add a four-up KPI card row under the header by default.
- Do not mirror the left and right sidebars.
- Do not use gradients in normal panes, segmented controls, or workbench buttons.
- Do not use multiple slider styles in one tool.
- Do not mix multiple button radii in the same control row.
- Do not box sliders, toggles, or small metrics in their own mini-cards.
- Do not append a page-level footer strip to a workbench.
- Do not redefine the core brand.css component classes.