Enforce design-system invariants for frontend UI

Design System is a set of mechanical implementation invariants for frontend design, meant to be applied alongside the companion design skill when building components, pages or design systems. Aesthetic direction lives elsewhere; this skill covers the rules that make an interface load and behave correctly, so that every color, type and motion choice traces back to them. It is a community skill by Conner K Ward under the MIT license.

• Token architecture: all colors map to a small set of primitives, with no random hex values: foreground (primary, secondary, muted text), background (base, raised, overlay surfaces), border (subtle, default, emphasis), brand, and semantic colors for destructive, warning, success and optional info. Use tokens in code, such as CSS variables or theme objects, and never hardcode hex for UI.
• Typography: headlines get heavier weight and tighter letter-spacing, body a comfortable weight, labels a medium weight that works small, and data monospace with tabular-nums. Combine size, weight and letter-spacing so hierarchy is clear at a glance; if you squint and cannot tell headline from body, it is too weak. Pair a display font with a body font. Monospace is for functional data such as aligned numbers, IDs and timestamps, not for decorative microtext.
• Loading order, first seen first loaded: the first viewport must paint complete and correct, so prioritize only the above-the-fold set (hero text, hero image or video, brand mark), since preloading everything is the same as preloading nothing. Self-host WOFF2 fonts (about half the bytes of OTF or TTF) and preload the weights used in the first viewport instead of using a render-blocking third-party font stylesheet. Give the hero image fetchpriority="high", preload it when CSS references it, and never leave the hero box empty. Below the fold use loading="lazy" decoding="async", preload="none" or "metadata" on video and defer on non-critical JS, always reserving space with aspect-ratio or width and height to avoid layout shift. Keep the render-blocking head minimal by inlining critical CSS.
• No font pop-in (FOUT): font-display: swap is itself the pop, so it must not be used for text the user watches load. Instead add a fonts-pending class in the head that holds display text at opacity: 0, call document.fonts.load for each critical face, and on document.fonts.ready switch to fonts-ready and fade the text in over about 0.5 seconds, with a safety timeout of about 2.5 seconds so a font failure never leaves text hidden. Where a subtle swap is tolerable for body text, tune a fallback face with size-adjust, ascent-override and descent-override so the swap shifts nothing.
• Slow-loading content: anything slow (fonts, large images, video, canvas, Three.js or WebGL scenes, lazy React islands) must either arrive fast, through compression such as WOFF2, Draco, WebP or AVIF, or load gracefully behind an intentional placeholder that fades to the real thing. Fixes include starting annotation labels at opacity: 0, showing a placeholder until a canvas paints its first frame, using aspect-ratio plus preload for images, matching video posters to a controlled still, keeping a 3D canvas at opacity: 0 until the loader succeeds, and replacing a Suspense spinner with a skeleton that traces the final layout. The test is whether a mid-load screenshot would be embarrassing.
• Chrome stays still: headers, navigation, toolbars and status regions keep a constant height however their text changes. Constrain status text to one line with white-space: nowrap; overflow: hidden; text-overflow: ellipsis and reserve a fixed height or min-height so the longest, shortest and empty states share one footprint.
• Motion: keep timing consistent and purposeful. One well-orchestrated staggered page load beats scattered micro-interactions; prefer CSS for HTML and a motion library for React, and honor prefers-reduced-motion on public or multi-user projects. Restrained defaults are about 150 ms for micro-interactions and 200 to 250 ms for larger transitions with ease-out, while a playful tone may use spring and longer beats.
• Scroll-driven narrative: for explanatory or editorial content, prefer a pinned sticky graphic driven by short scrolling text steps over click-to-advance widgets, using one IntersectionObserver with rootMargin of -48% 0px -48% 0px. Steps take about 85vh, inactive steps dim, and the graphic is a pure function of the active step. Do not use it for dashboards, tools or forms that users operate.
• Nested radii: a child radius never exceeds its parent's, and ideally is concentric: parent radius minus the gap between them.
• Color: derive the palette from the product's domain, let color carry meaning (gray for structure; color for status, action, emphasis and identity), use APCA for perceptual contrast decisions and WCAG 2 (4.5:1 and 3:1) as the compliance floor, and make hover, active and focus states more prominent than rest.

Backgrounds and detail follow the same restraint: atmosphere over flat fills, but matched to the chosen aesthetic, since a reflexive gradient-mesh, noise or grain treatment is itself a trend default and is reached for only when the direction genuinely calls for it.

Use it when implementing UI: components, pages or design systems. It is not the place for aesthetic direction, grid and spacing composition (covered by the design-spatial skill) or avoiding generic trend looks. Use it only when the task matches its upstream source and project context, verify generated code and dependencies, and get approval for destructive or costly actions.

Input is an interface or component to build or review. An example request is to review an interface, identify the highest-impact design problems and propose an implementation-ready improvement. Output is token-based CSS or theme code and specific fixes. A bundled motion choreography reference asks that every transition communicate something or be cut, ranks transitions by value (shared element, reveal, list identity, state change, route change), and matches style to navigation: directional slides for hierarchical or ordered navigation, and fades for lateral navigation between peers, since a slide falsely implies depth. It also gives duration ranges (100 to 200 ms for toggles, 150 to 250 ms for route changes, 200 to 400 ms for reveals, 300 to 500 ms for shared-element morphs), says to animate only transform and opacity, never transition: all, and keep motion interruptible, and covers motion blur on morphs, not scaling text bitmaps, isolating persistent chrome and delaying spinners by 150 to 300 ms.

It suits frontend developers and designers who want consistent tokens, fast and stable loading, and honest motion in production interfaces.