gacela-project/gacela-project.com/facet-component

Facet component

Facet (src/design) is plain CSS: custom properties for tokens, @layer for cascade order, one file per component. No framework, no build step.

@layer reset, tokens, base, layout, components, utilities;

Components belong in components. Needing !important or a long selector chain means the wrong layer.

Steps

1. Reuse. ls src/design/components/. Most new components are an existing one plus a modifier.
2. Tokens first. Every colour, space, radius, shadow and type size is a token. Add missing ones to src/design/tokens.css in the right scale, for both themes. A raw hex, rgb() or oklch() outside tokens.css is a bug; the convention guard hook reports it. Prefer semantic tokens (--surface-raised) over literal ones (--gray-100).
3. Write the component in src/design/components/<name>.css:

``css @layer components { .callout { --callout-accent: var(--color-accent); /* modifiers override only these */ padding: var(--space-4) var(--space-5); border-inline-start: 2px solid var(--callout-accent); background: var(--surface-sunken); border-radius: var(--radius-sm); } .callout--warning { --callout-accent: var(--color-warning); } } ``

One class per component, --modifier naming, no element selectors reaching outside it, logical properties (padding-inline), :focus-visible on anything interactive.

1. Register the @import in src/design/index.css, in layer order.
2. Both themes. Dark is a token swap, never a second stylesheet. Check that surfaces separate from the background, borders show without glowing, and text holds 4.5:1.
3. Show it on content/pages/design-system.md: default, each modifier, and the states that matter (hover, focus, disabled, empty, overflowing). An unlisted component drifts unseen.
4. Responsive without media queries first: clamp(), min(), repeat(auto-fit, minmax(..., 1fr)), container queries. Use a media query only when the layout changes shape.

Done

• npm run build; view the page at 1440px, 768px and 375px.
• Tab to the component: focus is visible.
• With JavaScript disabled it still looks right.
• Animation under 300ms, inside prefers-reduced-motion: no-preference.