| name | styling |
| description | How-to for non-trivial UI/styling work in starlib. Use when adding or changing component visuals, layout chrome, tokens, themes, or anything touching globals.css, tailwind utilities, or files under src/components/ui/*. |
Styling
This skill is the procedural companion to DESIGN.md (repo root). DESIGN.md is the declarative spec — what the tokens, components, and layout should be. This skill is the how-to — what to do before, during, and after a styling change.
If the two ever disagree, DESIGN.md wins and this skill gets updated.
Before you touch anything
- Read the relevant DESIGN.md section. Tokens live in §2, type in §3, spacing §4, radii §5, components §9, layout §10. Cite the section in your response so the user can verify you're working from the spec, not from training-data intuition.
- Check
frontend/src/app/globals.css. Primitive tokens (--surface-*, --text-*, --brand*, --border*) and their shadcn aliases live there. If the token you want doesn't exist, either DESIGN.md covers it (add the token per §2) or you're about to invent a new one — stop and raise it.
- Open
/design (the in-app showcase at frontend/src/app/design/page.tsx) for any visual changes. It is the fastest way to see what tokens and components actually look like together across light + dark.
While you work
- Use primitive tokens in new code.
bg-[var(--surface-2)], text-[var(--text-muted)], etc. shadcn alias names (bg-background, text-muted-foreground) stay legal only inside src/components/ui/* — those files are shadcn-sourced and left alone.
- Never introduce a token inside a component file. Tokens live in
globals.css. If you find yourself writing a one-off oklch(...), stop.
- Never hand-pick hexes for UI color. Derive from the three knobs (
--base-hue, --accent-hue, --contrast) per §2.2. Hexes exist in DESIGN.md only as human-readable annotations on OKLCH values.
- Match existing density. 28px controls, 40px table rows, 44px top bar, 56px sidebar rail (§4, §10). Don't invent arbitrary paddings (
p-[11px]) in committed code.
- One primary per view. Button variant
default is for the single primary action (§9.1). secondary is the default choice for most actions.
- Respect the accent.
--brand solid goes on primary action + focus ring only. Selected/active state uses --brand-soft. Never paint large regions with --brand itself. Never apply the accent to decoration, dividers, or non-"current" status (§9.8).
- Borders before shadows. Use
--border for separation (§6). Shadows (§7) are for floating layers only.
- Motion ≤
--dur-4 (320ms). Longer is decoration, not confirmation (§8). Honor prefers-reduced-motion.
Verify before reporting done
When the spec is wrong
DESIGN.md is prescriptive, not a straitjacket (§12). If you find yourself breaking a rule in three places, the rule is wrong — update DESIGN.md. If you break a rule once because of a legitimate constraint (third-party embed, user research finding, marketing surface), document it in the change that breaks the rule.
What NOT to do
- Don't refactor adjacent styling that isn't broken. Surgical changes only.
- Don't "improve" shadcn primitives in
src/components/ui/* — they use shadcn's token vocabulary by design.
- Don't add a new color, radius, duration, or density step without updating DESIGN.md in the same change.
- Don't rely on screenshots alone for dark-mode verification — toggle the theme and look.
