css-standards

Files (5)

• SKILL.md
• css-standards.md · references/
• card.css · references/mini-project/web/src/css/components/
• home.css · references/mini-project/web/src/css/
• tokens.css · references/mini-project/web/src/css/

SKILL.md (first lines)

# CSS Standards

Use this skill when a frontend project needs a consistent, maintainable CSS architecture for shared tokens, page entry styles, component partials, and brand-driven visual language.

## Automatic Companion Skills

- **Aesthetic Direction & Tokens**: Pair with [`frontend-design`](../frontend-design/SKILL.md) to define intentional palettes, display/body typographic hierarchies, and avoid generic templated defaults.
- **Craft & Accessibility**: Pair with [`impeccable`](../impeccable/SKILL.md) for surface modes, responsive spacing floors, dark/light theme tokens, and accessible focus states.
- **Validation**: Pair with [`ui-ux-auditor`](../ui-ux-auditor/SKILL.md) to visually audit rendered styles and breakpoint transitions in real browser views.

## Scope

- Applies to styles under `web/src/css/`.
- Applies to class names used in `web/view/*.html`.
- Applies to browser components that toggle visual state from `web/src/js/components/`.

## Visual Direction

- Prefer a warm, readable public app appearance over a generic admin-style theme.
- Keep hero sections, event/showcase layouts, and modal/profile surfaces visually consistent.
- Preserve existing brand cues and palette tokens rather than introducing a new theme.
- Avoid migrating the site toward a different source project's palette or generic admin UI language.

## Typography and Icons

- Define default fonts, font family CSS variables (`var(--font-body)`, `var(--font-display)`, `var(--font-mono)`) and any other relevant font variables to the project and icon imports in the shared tokens/common stylesheet.
- Always use font CSS variables (`var(--font-*)`) instead of hardcoding literal font family names in leaf or partial stylesheets.
- Do not add new font or icon imports inside leaf CSS files.
- Reserve special accent typefaces for the cases the UI already uses, not for arbitrary styling.
- Prefer a single shared icon system for the app. Keep icon styling tied to the package-provided CSS variables or documented API instead of version-pinned font-family names.
- Keep visible labels alongside icons in buttons, chips, cards, links, and modal actions unless the control is already clearly labeled for accessibility.

## Responsive Rules

- CSS must be mobile first: define the base layout for `0px` first, then enhance it with `min-width` media queries.
- Do not use `max-width` breakpoints unless the user explicitly asks for them.
- Use this default breakpoint scale:
  - `Base`: `0`
  - `sm`: `640px`
  - `md`: `768px`
  - `lg`: `1024px`
  - `xl`: `1280px`
  - `2xl`: `1536px`
- Keep responsive overrides close to the selectors they modify rather than moving them to a detached responsive section.
- When a repository already has its own documented breakpoint contract, follow that local rule instead of introducing a competing scale.
- On phone layouts, prefer flush section shells when they improve readability: outer wrappers may drop to `padding: 0`, large sections/panels/modals may tighten to a smaller radius, and the breathing room should move into inner headers, bodies, facts, and action rows instead of staying on the outer shell.
- Restore the roomier framed-card treatment at the first upward breakpoint used by the project rather than preserving desktop gutters on narrow screens.

## Selector Nesting

- Prefer native CSS nesting for a component's pseudo-elements, states, descendants, and component-local parts. Keep the component root as the outer rule so related selectors stay colocated.
- Use `&` when the nested selector changes the same element: `&:hover`, `&:focus-visible`, `&::before`, `&::backdrop`, `&[open]`, and `&.is-active`.
- Use a bare nested selector for a descendant: `.modal-dialog {}` inside `.modal {}` means `.modal .modal-dialog`.
- Nest state rules inside the element they modify. Write `.modal-close { &:hover { ... } }`, not a separate `.modal-close:hover` block at the component root.
- Keep nesting shallow. A component root, its local part, and that part's state is a useful default; avoid deep selector chains and nesting unrelated component roots.
- Keep global rules, shared structural classes, and independently reusable component roots flat. Use nesting for ownership and colocation, not as a replacement for clear class names.

Preferred shape:

```css
.modal {
    /* Root styles */

    &::backdrop {
        /* Pseudo-element of .modal */
    }

    &:not([open]) {
        /* State of .modal */
    }

    .modal-dialog {
        /* Descendant owned by .modal */
    }

    .modal-close {
        /* Descendant owned by .modal */

        &:hover {
            /* State of .modal-close */
        }
    }
}
```

## Core Rules

1. `web/src/css/tokens.css` owns shared CSS variables, font imports, and global browser chrome such as scrollbar styling.
2. Page CSS entry files should import `./tokens.css` first, then the component partials they need.
3. Reuse existing shared color tokens and font variables (`var(--font-*)`) from the shared stylesheet instead of hardcoding duplicate palette values or literal font strings.
4. Use `var(--token)` for pure shared colors and font family variables (`var(--font-body)`, `var(--font-display)`, etc.).
5. Use `rgb(from var(--token) r g b / alpha)` when a shared color needs opacity.
6. Use `color-mix(...)` or another standards-compliant blend only when the result is not a pure shared color.
7. Prefer consistent plain-CSS media queries using `min-width` and the shared breakpoint scale: `640px`, `768px`, `1024px`, `1280px`, `1536px`.
8. Keep page entry files as composition layers: imports first, then only page-level layout and one-off scaffolding.
9. Shared structural shells should live in reusable classes such as `.surface-host` and `.surface-card`, or equivalent project naming, rather than being re-declared inside every semantic component selector.
10. Each reusable UI component should own its style file. If a page entry starts carrying multiple component roots, extract them instead of extending the entry file.
11. If a page-specific component is only a contextual variant of a reusable component, keep the shared visual primitive in the reusable component file and limit the page-specific file to contextual overrides and container-specific states.
12. If multiple page-scoped components share the same visual primitive and there is no reusable base component yet, extract a small shared partial or shared structural class instead of duplicating rules or pushing them back into the entry file.
13. Prefer multiple classes on the same element when structure and meaning are different concerns: semantic classes for purpose and JS hooks, structural classes for reusable shells and spacing contracts. Do not use `data-*` attributes. Never store domain data (IDs, values, lookup mappings) in data attributes — that data belongs in JavaScript structures resolved at interaction time.
14. Prefer native CSS nesting within each component file: nest pseudo-elements, same-element states with `&`, and component-owned descendants under their root selector. Follow the `&` versus descendant rules in the Selector Nesting section.
15. Keep responsive overrides in the same component file as the base styles they modify.
16. Keep component styles in their existing partials such as `modal.css`, `menu.css`, `toast.css`, etc., rather than creating new ones for one-off treatments. If a new reusable visual primitive emerges, give it its own CSS partial instead of burying it in an unrelated page file.
17. Prefer CSS class toggles over inline styles. Dynamic asset URLs or one-off image backgrounds are the exception, not the default.
18. Keep interactions visually controlled: subtle lift, border shifts, and shadow changes are usually better than aggressive transforms or high-contrast effects.
19. Scope `&[hidden] { display: none; }` inside component selectors (or use higher-hierarchy `[hidden]` selectors) whenever a component rule sets an explicit `display` property, ensuring `[hidden]` takes effect without needing `!important`.

## Structural Classes

- Separate semantic classes from structural classes whenever a project has repeated shells.
- Semantic classes should answer what the element is in the product: `.panel`, `.profile-card`, `.settings-section`, `.feature-grid`.
- Structural classes should answer what reusable shell pattern it uses: `.surface-host`, `.surface-card`, `.surface-subtle`, or whatever equivalent naming the project already uses.
- Prefer adding a structural class in markup over inventing a new selector that only restates border, radius, background, shadow, and base padding.
- Keep the structural class layer small. This is not a license to turn the project into utility-class soup.
- When HTML is generated from JavaScript, include the structural class in the generated `className` so client-rendered elements follow the same visual contract as server-rendered markup.

## Guardrails

- Do not import a new design system or generic admin theme.

From werlang/user-skills, MIT.

More from werlang/user-skills