frontend-design

What this skill does

# Frontend Design

This is a visual design guardrail skill, not a domain workflow skill. Domain skills own required product structure, terminology, workflows, and output views. This skill owns visual quality and must be applied inside that structure.

## Mandatory References

Before visual planning or implementation, read both files. Skipping either file is a skill violation.

- `.agents/skills/frontend-design/references/visual-style-references.md`
- `.agents/skills/frontend-design/references/shadcn-setup-and-theming.md`

## Required Workflow

1. Read the active task, domain context, and selected domain skills.
2. Read `.tasks/domain.md` when it exists. Extract brand colors, company name, domain tone, terminology, workflows, entities, statuses, roles, and constraints.
3. Read both frontend-design references.
4. Produce the design pass before coding:
   - **Vision**: domain-specific product and visual direction. Reject generic SaaS purple, card-heavy dashboards, and generic admin shells.
   - **First-version features**: working screens, controls, routes, dialogs, and localStorage-backed state.
   - **Design tokens**: primary, secondary/accent, background, canvas, focal contrast treatment, text, border, radius, contact shadow, status colors, typography, generous spacing, and cardless plan.
   - **Design direction**: enforce brand color usage, actual logo usage, airy spacing, airy inner density, rounded controls, strong input contrast, soft/tight shadows, minimal visual noise, cardless defaults, and authored composition. Where the selected domain skill does not specify structure, use stronger visual ideas like asymmetry, deliberate negative space, vivid accent hierarchy, motion, and atmospheric background detail.
5. Pass the design compliance gate.
6. Configure CSS variables, Tailwind/shadcn theme tokens, and the relevant shadcn component styles before building screen details.
7. Build the UI with those tokens. Use Tailwind where it is useful, and write custom CSS classes when Tailwind is limiting; custom CSS must reuse the global CSS variables, radius, color, and shadow tokens.
8. Run the pre-completion audit and revise before finishing.

## Non-Negotiables

- **Brand first**: If `.tasks/domain.md` provides brand colors, use them. Map the main brand/accent color to primary actions, active navigation, selected state, focus, and links. Derive neutral surfaces, borders, muted text, and statuses from compatible tints. Do not default to generic purple/blue.
- **Readable foregrounds always**: Use brand colors for primary, secondary, accent, active, and focus roles, but choose foreground/text colors separately for legibility. Brand palettes usually do not provide all text colors. Every text, icon, label, placeholder, badge, button, disabled state, and data value must have high contrast against its actual background. When a brand color is the background, derive a readable foreground color for it instead of reusing another brand color. Prefer WCAG AA as the minimum: `4.5:1` for normal text and `3:1` for large text/icons.
- **Domain-skill compatibility**: If the app fits a selected business/domain skill like CPQ, CRM, trades, or similar, follow that skill's required workflow, terminology, and layout structure. For anything the domain skill does not specify, use this skill's visual rules and composition guidance rather than falling back to a generic admin shell.
- **Authored composition**: Every app should feel intentionally designed. Commit to a cohesive aesthetic, use CSS variables consistently, prefer dominant colors with sharp accents over timid evenly distributed palettes, use motion for high-impact moments, favor asymmetry or unexpected composition where it does not conflict with workflow clarity, and build atmosphere through brand-compatible backgrounds and visual details.
- **Use the real logo**: First look in `public/brand/logos/`. If that folder contains a usable logo file, use the correct actual logo from that folder in the header or primary app chrome. Only create or invent a logo if `public/brand/logos/` does not exist or has no usable logo files.
- **Cardless by default**: Aim for zero cards. If the UI works without a card, the card is not allowed. A bordered rounded surface occupying a major region of the page is a card even if `Card` is not imported. Cards are only allowed for dialog/popover/sheet containment, concise notice, or truly repeated items when rows, dividers, or tonal separation fail.
- **No top-level cards**: Never compose the main page from large sibling cards, a stack/grid of rounded panels, or a large framed hero/detail container. Top-level structure must be open sections, tonal bands, rows, dividers, workspace areas, or one open focal working zone.
- **No sidebars by default**: Use a sidebar only when the user explicitly asks for one or a selected domain skill explicitly requires one. Do not add a sidebar because the app is operational, business, admin-like, multi-step, or has multiple sections.
- **Airy spacing**: Use generous gaps, gutters, row rhythm, and section spacing. Slightly too much spacing is acceptable; cramped, dense, or compressed UI is failure.
- **Airy inner density**: Airiness must continue inside rows, tables, lists, cards, and compound components. Do not pack too many columns into one row when a cleaner stacked or richer row layout would breathe better. Inner content should use generous gaps between sub-elements, metadata, actions, and labels.
- **Table rhythm**: When using a surfaced table, give the table `shadow-xs` and use generous header padding, row padding, and taller row rhythm. Tables should not feel compressed, flat, or spreadsheet-tight.
- **Rounded by default**: If the selected domain skill does not explicitly require a sharper or specific radius language, prefer a clearly rounded modern system. Avoid timid 4px/6px/8px admin radii by default. Controls, chips, tabs, and key surfaces should usually feel distinctly rounded or pill-like.
- **Typography with character**: Choose fonts that are beautiful, distinctive, and interesting. Avoid generic defaults like Arial and Inter. Prefer a characterful display face paired with a refined body face when the product can support it. The typography should elevate the UI, not read like a default starter app.
- **One dominant working surface**: The first screen should focus on one clear operational object or working section. Do not try to show the whole product at once.
- **No major-region framed surfaces**: Do not turn the main working area, hero, inspector, or detail lane into a big bordered rounded panel. Prefer open layout, split rows, tonal bands, dividers, or a drawer/sheet for secondary detail.
- **Token-first shadcn and CSS**: Configure `app.css`/global CSS variables, Tailwind theme values, and relevant shadcn component styles before component work. Do not accept default shadcn colors or component styling as the design. shadcn components are base primitives only; always customize their classes/styles to fit the app's tokens, spacing, contrast, radius, shadow, and interaction rules. Tailwind is not mandatory for every visual decision; write custom CSS when it creates a more distinct, minimal, polished UI, while reusing the same CSS variables and theme tokens.
- **Strong soft contrast**: If a surface exists, it must separate from the canvas through tone first, border second, shadow last. Same-white or near-white surfaces with faint borders fail.
- **Interactive surface contrast**: Every editable control must be obvious. Regular text inputs, selects, textareas, comboboxes, date fields, search fields, command-bar controls, and shadcn form controls must all use a near-white or very light tinted background in light mode and a near-black background in dark mode. Do not only fix selects while leaving normal inputs page-colored. Controls must not use `bg-transparent`, `bg-background`, `bg-muted`, or the same fill as the page/panel. `--input` must be visibly lighter