frontend-design

Files (1)

• SKILL.md

SKILL.md (first lines)

# frontend-design (dev-time)

A contributor workflow for editing **AI Atelie's own chrome** — the parts of the host app a user sees regardless of what they're designing inside the canvas. Dev-time only; does not load into adapter sessions spawned by the editor.

If you're editing the canvas frame, the chat sidebar, the toolbar, the projects screen, the settings dialog, or any CSS module under `web/src/`, this skill applies. If you're editing a SKILL.md under `skills/<name>/` that governs *user-generated designs*, this skill does NOT apply — that's the product skill, a different surface.

## Read the atelier first

[`atelier/`](../../../atelier/) is AI Atelie's canonical craft rulebook. Tokens in [web/src/index.css](../../../web/src/index.css) decide *what* the brand looks like; the atelier files decide *how* a competent designer uses them.

The frontmatter `craft.requires` declares which sections this skill depends on. Pull these into context before touching chrome — they are the floor, not aspiration:

| Atelier file | What it covers | When you need it |
|---|---|---|
| [atelier/typography.md](../../../atelier/typography.md) | Type scale, line height, **ALL CAPS tracking floor (≥0.06em)**, font pairing, three-weight system, line length | Any text on screen |
| [atelier/color.md](../../../atelier/color.md) | Palette structure (70-90% neutrals / 5-10% brand / 0-5% semantic / <1% effect), **≤2 visible `--brand` uses per screen**, ink scale by job, contrast minimums, semantic naming | Any styled surface |
| [atelier/anti-ai-slop.md](../../../atelier/anti-ai-slop.md) | The 7 P0 cardinal sins (lint-enforced): no Tailwind indigo, no two-stop trust gradients, no emoji-as-icons, no hardcoded display fonts, no rounded-card-with-left-border, no invented metrics, no filler copy. Plus soft tells and a chrome-PR checklist | Every chrome PR |
| [atelier/state-coverage.md](../../../atelier/state-coverage.md) | Empty / loading / error states for any data-fetching surface | Anything that lists, fetches, or paginates |
| [atelier/animation-discipline.md](../../../atelier/animation-discipline.md) | Motion tokens, `prefers-reduced-motion`, when motion earns its place | Anything that animates |
| [atelier/accessibility-baseline.md](../../../atelier/accessibility-baseline.md) | Contrast, keyboard, focus rings, ARIA on chrome | Any interactive control |

If a question comes up that one of those files answers, check there first before improvising. Don't duplicate the rules into this skill — the atelier is the source of truth.

## Chrome posture (what atelier doesn't already cover)

The chrome serves the canvas. **Restraint over flourish.** Maximalism belongs *inside* the canvas (user-generated designs); the toolbars surrounding it should recede.

Three things shape every chrome decision in AI Atelie that the universal atelier rules don't address:

**Two axes drive the chrome.** Defined in [web/src/lib/theme.ts](../../../web/src/lib/theme.ts).

- `theme` — `system | light | dark | retro` — brightness preference.
- `design` — `null | violet | mono | paper | espresso | coral | ember | vinyl | scarlet | glacier | phosphor | hornet | prism` — opt-in decorative overlay; 12 palettes generated by [tools/gen-themes.mjs](../../../tools/gen-themes.mjs).
- Both apply through one `data-theme` attribute on `<html>`. Picking a theme clears the design (so "click → see change" stays honest).

Every chrome edit must work across the canonical (theme + design = null) AND across Dark and Retro themes; spot-check Violet + Mono designs as a smoke test.

**Canonical default look.** Warm cream surface (`--app-bg: #faf9f5`) + Claude rust accent (`--brand: #c96442`) + dense alpha ink scale (25+ stops from `--ink-02` through `--ink-92`). The 12 designs are decoration the user opts into — build for the canonical first, verify in overlays after.

**Six fonts loaded globally.** [index.css:11](../../../web/src/index.css:11) imports JetBrains Mono / Archivo / Syne / Noto Sans JP / Antonio / Instrument Serif. Use them with intent — mono for code, paths, kbd hints; display for hero or section openers; italic serif for editorial flourish. Don't add a font import inside a single component — extend the global `@import` with a documented reason.

## Hard rules specific to chrome — and what to do INSTEAD

These complement [atelier/anti-ai-slop.md](../../../atelier/anti-ai-slop.md), which has the universal lint-enforced rules. Below are the rules specific to AI Atelie's two-axis chrome.

- **Don't ship chrome that's only verified in default theme.** A token that exists in only one theme silently breaks when the user switches. **INSTEAD**: after implementing, toggle through Light → Dark → Retro using the theme picker (foot pill or Settings → Appearance). Spot-check Violet + Mono designs. If anything breaks, the tokens picked were too narrow.
- **Don't add a token at `:root` without mirroring it in every override block.** **INSTEAD**: edit `:root`, then `[data-theme="dark"]` and `[data-theme="retro"]` (both at the bottom of `index.css`), then either regenerate the 12 designs via `tools/gen-themes.mjs` or hand-edit `styles/themes.css` for each. A token that exists in only one theme is a bug.
- **Don't write `[data-theme="dark"] .myComponent { ... }` overrides inside a component's CSS module.** That bypasses the token layer. **INSTEAD**: add the token at `:root` with one default value, then a different value per theme override block. The component reads `var(--token)` once. (This is also called out in [atelier/anti-ai-slop.md](../../../atelier/anti-ai-slop.md) as a soft tell.)
- **Don't introduce a new design or theme axis on a feature PR.** **INSTEAD**: scope theme system changes to dedicated PRs (mirror [#80](https://github.com/aiatelie/ai-atelie/pull/80) for the prior 12-palette landing). Decoration drift on feature PRs erodes the system.
- **Don't reach for a font import inside a component.** **INSTEAD**: pick the existing role from the six globally loaded faces. If a new role genuinely is missing, extend `@import` in `index.css` and explain the new role in the commit body.

## When to invoke

- Any diff that adds, modifies, or removes CSS in `web/src/`.
- Any diff that adds or modifies a TSX/JSX component with visible UI.
- Any change to `web/src/lib/theme.ts` or the generated [styles/themes.css](../../../web/src/styles/themes.css).
- Before creating a new component — read the closest neighbour's module first.
- When the user says "make this prettier", "the editor looks broken in Dark", "match the design language", or "ship a UI polish pass".

Skip when:
- The change is api-only, mcp-only, or build-config-only with no UI surface.
- The diff touches only `web/projects/` (user data, not chrome).
- The diff is to `skills/<name>/SKILL.md` — that's the product skill, a different scope.

## Workflow

1. **Read the atelier sections in `craft.requires`** at the top of this file. Open them in your context before editing — the loader for the `craft` field is not yet implemented, so the agent must pull them in directly.
2. **Read the neighbour first.** Open the closest sibling component's `*.module.css` and adopt its conventions before inventing new ones.
3. **Read the relevant section of [index.css](../../../web/src/index.css).** The annotation comments are part of the design-system docs.
4. **Implement using only tokens.** No literals, no per-component fonts, no inline color styles.
5. **Run `bun run dev`.** Vite binds `localhost`/IPv6 (not `127.0.0.1`); the live-preview process auto-restarts on `:5173` if killed, so don't fight it.
6. **Verify the canonical theme works** via [`.claude/skills/verify-with-playwright/SKILL.md`](../verify-with-playwright/SKILL.md).
7. **Spot-check the other axes.** In the running browser, open Settings, switch theme through Light → Dark → Retro, then turn on Violet and Mono designs. Fix at the token layer, not the component, if anything breaks.
8. **Commit via [`.claude/skills/semantic-commit/SKILL.md`](../semantic-commit/SKILL.md)** with `scope=web`.

## When this skill is wrong

This skill encodes the conventions in place when it was written. If the user is intentionally evolving the system — landing a new design overlay, refactoring the token layer, replacing the font stack, expanding the atelier — the rules describe the *current* state, not a constraint on the future. Follow the user's lead, then update this skill (and the relevant atelier file, if changed) in the same PR so the next contributor sees the new ground truth.

## See also

- [atelier/](../../../atelier/) — the universal craft rulebook this skill opts into.
- [atelier/README.md](../../../atelier/README.md) — how the rulebook is structured and the `craft.requires` opt-in protocol.
- [web/src/index.css](../../../web/src/index.css) — token source of truth.
- [web/src/styles/themes.css](../../../web/src/styles/themes.css) — generated 12-design overrides.
- [web/src/lib/theme.ts](../../../web/src/lib/theme.ts) — theme + design axis definitions.
- [tools/gen-themes.mjs](../../../tools/gen-themes.mjs) — palette generator.
- [.claude/skills/verify-with-playwright/SKILL.md](../verify-with-playwright/SKILL.md) — capture chrome evidence.
- [.claude/skills/cuj-guardian/SKILL.md](../cuj-guardian/SKILL.md) — gate before approving any UI PR.
- [skills/frontend-design/SKILL.md](../../../skills/frontend-design/SKILL.md) — the product skill that governs *user-generated* designs in the canvas; this dev-time skill is its mirror for *the host app's chrome*.

From aiatelie/ai-atelie, MIT.

More from aiatelie/ai-atelie