Fix UI/UX audit findings: accessibility, tokens, hooks, design system page

- Improve textMuted contrast (alpha 0.45 → 0.55) for WCAG AA compliance
- Normalize hex color tokens to HSL; add fontSizes scale
- Add injectGlobalStyles() for focus-visible rings and reduced-motion
- Add useReducedMotion() and useHoverLift() hooks; deprecate hoverLiftHandlers
- Add ctaLink prop to Header; add data-fzui and 44px touch target to CopyButton
- Migrate ProjectCard and GettingStartedPage to useHoverLift hook
- Add reduced-motion overrides to Hero keyframes
- Add /design-system living style guide page
- Embed full design system documentation as JSDoc in index.ts

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: gmoon

packages/ui/src/components/CopyButton.tsx

@@ -1,7 +1,9 @@
 import { useState, useEffect, useRef } from 'react'
 import { colors, fonts } from '../tokens'
+import { injectGlobalStyles } from '../styles'
 
 export function CopyButton({ text }: { text: string }) {
+  injectGlobalStyles()
   const [copied, setCopied] = useState(false)
   const timerRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
 
@@ -23,6 +25,7 @@ export function CopyButton({ text }: { text: string }) {
   return (
     <button
       onClick={handleCopy}
+      data-fzui
       style={{
         position: 'absolute',
         top: '0.5rem',
@@ -32,6 +35,10 @@ export function CopyButton({ text }: { text: string }) {
         border: 'none',
         borderRadius: '4px',
         padding: '0.3rem 0.6rem',
+        minHeight: '2.75rem',
+        display: 'inline-flex',
+        alignItems: 'center',
+        justifyContent: 'center',
         fontSize: '0.75rem',
         fontFamily: fonts.system,
         cursor: 'pointer',

packages/ui/src/components/Footer.tsx

@@ -1,4 +1,5 @@
 import { colors, fonts } from '../tokens'
+import { injectGlobalStyles } from '../styles'
 
 export interface FooterProps {
   repoUrl?: string
@@ -23,8 +24,9 @@ const styles = {
 }
 
 export function Footer({ repoUrl, repoLabel, orgName }: FooterProps) {
+  injectGlobalStyles()
   return (
-    <footer style={styles.footer}>
+    <footer style={styles.footer} data-fzui>
       <p>
         &copy; {new Date().getFullYear()} {orgName ?? 'Forkzero'}.{' '}
         {repoUrl ? (

packages/ui/src/components/Header.tsx

@@ -1,4 +1,5 @@
 import { colors, fonts } from '../tokens'
+import { injectGlobalStyles } from '../styles'
 
 export interface HeaderLink {
   label: string
@@ -9,6 +10,7 @@ export interface HeaderProps {
   minimal?: boolean
   navLinks?: HeaderLink[]
   githubUrl?: string
+  ctaLink?: { label: string; href: string }
 }
 
 export interface PoweredByHeaderProps {
@@ -54,6 +56,18 @@ const styles = {
     fontFamily: fonts.system,
     transition: 'color 0.2s',
   },
+  ctaLink: {
+    color: colors.accentBlue,
+    textDecoration: 'none',
+    fontSize: '0.9rem',
+    fontFamily: fonts.system,
+    fontWeight: 600,
+    background: 'rgba(0, 255, 255, 0.1)',
+    padding: '0.4rem 0.8rem',
+    borderRadius: '6px',
+    border: `1px solid ${colors.accentBlue}`,
+    transition: 'background 0.2s',
+  },
   navLinkGh: {
     color: '#ffffff',
     textDecoration: 'none',
@@ -67,9 +81,10 @@ const styles = {
   },
 }
 
-export function Header({ minimal, navLinks, githubUrl }: HeaderProps) {
+export function Header({ minimal, navLinks, githubUrl, ctaLink }: HeaderProps) {
+  injectGlobalStyles()
   return (
-    <header style={styles.header}>
+    <header style={styles.header} data-fzui>
       <a href="/" style={styles.logo}>
         <span style={styles.logoBold}>FORK</span>
         <span style={styles.logoThin}>ZERO</span>
@@ -81,6 +96,11 @@ export function Header({ minimal, navLinks, githubUrl }: HeaderProps) {
               {link.label}
             </a>
           ))}
+          {ctaLink && (
+            <a href={ctaLink.href} style={styles.ctaLink}>
+              {ctaLink.label}
+            </a>
+          )}
           {githubUrl && (
             <a href={githubUrl} target="_blank" rel="noopener noreferrer" style={styles.navLinkGh}>
               GitHub
@@ -93,8 +113,9 @@ export function Header({ minimal, navLinks, githubUrl }: HeaderProps) {
 }
 
 export function PoweredByHeader({ poweredByUrl, poweredByLabel }: PoweredByHeaderProps) {
+  injectGlobalStyles()
   return (
-    <header style={{ ...styles.header, padding: '0.75rem 2rem' }}>
+    <header style={{ ...styles.header, padding: '0.75rem 2rem' }} data-fzui>
       <a href="/" style={styles.logo}>
         <span style={styles.logoBold}>FORK</span>
         <span style={styles.logoThin}>ZERO</span>

packages/ui/src/index.ts

@@ -1,4 +1,161 @@
-export { colors, shadows, radius, fonts, gradient } from './tokens'
+/**
+ * @forkzero/ui — Shared design system for Forkzero applications.
+ *
+ * ## Quick start
+ *
+ * ```ts
+ * import {
+ *   colors, fonts, fontSizes, shadows, radius, gradient,
+ *   pageWrapper, cardBase, codeBlock, inlineCode, sectionTitle,
+ *   containerNarrow, containerWide,
+ *   useHoverLift, useReducedMotion, injectGlobalStyles,
+ *   Header, PoweredByHeader, Footer, CopyButton,
+ * } from '@forkzero/ui'
+ * ```
+ *
+ * ## Tokens
+ *
+ * ### Colors (`colors`)
+ *
+ * | Token           | Purpose                                          |
+ * |-----------------|--------------------------------------------------|
+ * | `bgPrimary`     | Main page background                             |
+ * | `bgSecondary`   | Slightly darker background (page wrapper default) |
+ * | `bgCard`        | Card / elevated surface background                |
+ * | `bgDeep`        | Deepest background (code blocks, inset areas)     |
+ * | `bgGlass`       | Semi-transparent header backdrop                  |
+ * | `textPrimary`   | Primary text (headings, labels)                   |
+ * | `textOnAccent`  | Text on accent-colored backgrounds                |
+ * | `textSecondary` | Body text, descriptions                           |
+ * | `textMuted`     | Captions, hints, metadata — WCAG AA compliant     |
+ * | `borderColor`   | Subtle borders on cards and dividers               |
+ * | `accentBlue`    | Primary accent — links, CTAs, focus rings          |
+ * | `accentGreen`   | Success states, available badges                   |
+ * | `accentYellow`  | Warnings, requirement layer                        |
+ * | `accentRed`     | Errors, destructive actions                        |
+ * | `accentPurple`  | Thesis layer, secondary accent                     |
+ *
+ * Always use tokens — never hardcode color values. For opacity variants
+ * use template literals: `` `${colors.accentGreen}14` `` (hex alpha suffix).
+ *
+ * ### Typography (`fonts`, `fontSizes`)
+ *
+ * - `fonts.system` — UI text, headings, body copy
+ * - `fonts.mono` — Code blocks, technical labels, CLI output
+ * - `fontSizes` — Scale from `xs` (0.75rem) to `3xl` (2rem)
+ *
+ * ### Shadows (`shadows`)
+ *
+ * - `shadows.sm` — Subtle cards, badges
+ * - `shadows.md` — Default card elevation (used by `cardBase`)
+ * - `shadows.lg` — Hover-lifted / emphasized cards
+ *
+ * ### Other
+ *
+ * - `radius` — Standard border radius (8px)
+ * - `gradient` — Hero/section gradient background
+ *
+ * ## Style objects
+ *
+ * Pre-composed `CSSProperties` objects. Spread and extend as needed:
+ *
+ * ```ts
+ * const myCard = { ...cardBase, padding: '1.5rem', marginBottom: '1rem' }
+ * ```
+ *
+ * | Object            | Use for                                    |
+ * |-------------------|--------------------------------------------|
+ * | `pageWrapper`     | Top-level page `<div>` (bg, min-height, font) |
+ * | `cardBase`        | Any card surface (bg, radius, shadow, border)  |
+ * | `codeBlock`       | `<pre>` code blocks                            |
+ * | `inlineCode`      | `<code>` inline snippets                       |
+ * | `sectionTitle`    | `<h2>` section headings                        |
+ * | `containerNarrow` | Centered content column (max 800px)            |
+ * | `containerWide`   | Centered content column (max 1200px)           |
+ *
+ * ## Hooks
+ *
+ * ### `useHoverLift(defaultShadow?)`
+ *
+ * Returns `{ style, handlers }`. Apply both to a card/link element for a
+ * lift-on-hover effect. Automatically disabled when the user prefers
+ * reduced motion. Replaces the deprecated `hoverLiftHandlers` function.
+ *
+ * ```tsx
+ * function Card() {
+ *   const { style, handlers } = useHoverLift(shadows.md)
+ *   return <div style={{ ...cardBase, ...style }} {...handlers}>...</div>
+ * }
+ * ```
+ *
+ * For elements rendered in a loop, wrap in a component so the hook is
+ * called per-instance (hooks cannot be called conditionally or in loops).
+ *
+ * ### `useReducedMotion()`
+ *
+ * Returns `boolean` — `true` when the user's OS prefers reduced motion.
+ * Use to conditionally skip custom animations.
+ *
+ * ### `injectGlobalStyles()`
+ *
+ * Call once (idempotent) to inject global CSS:
+ * - `:focus-visible` ring (2px solid accentBlue, 2px offset) on elements
+ *   inside `[data-fzui]` containers
+ * - `prefers-reduced-motion: reduce` suppression of animations/transitions
+ *   inside `[data-fzui]` containers
+ *
+ * All built-in components (Header, Footer, CopyButton) call this
+ * automatically. When building custom components, call it and add
+ * `data-fzui` to your root element.
+ *
+ * ## Components
+ *
+ * ### `<Header>`
+ *
+ * Props:
+ * - `navLinks?: { label: string; href: string }[]` — nav items
+ * - `githubUrl?: string` — renders a GitHub pill button
+ * - `ctaLink?: { label: string; href: string }` — accent CTA pill
+ *   between nav links and GitHub button
+ * - `minimal?: boolean` — logo only, no nav
+ *
+ * ### `<PoweredByHeader>`
+ *
+ * Compact header for embedded/sub-apps.
+ * Props: `poweredByUrl?`, `poweredByLabel?`
+ *
+ * ### `<Footer>`
+ *
+ * Props: `repoUrl?`, `repoLabel?`, `orgName?`
+ *
+ * ### `<CopyButton>`
+ *
+ * Props: `text: string` — the value copied to clipboard.
+ * Position inside a `position: relative` container.
+ * Has a 44px min touch target for mobile accessibility.
+ *
+ * ## Accessibility checklist
+ *
+ * - Add `data-fzui` to root elements of custom components
+ * - Call `injectGlobalStyles()` in component render (idempotent)
+ * - Use `useHoverLift` (not `hoverLiftHandlers`) for motion-safe hover
+ * - Buttons/links must be at least 44px in the smallest dimension
+ * - Use `textMuted` (not lower-alpha values) for de-emphasized text
+ *
+ * ## Branding
+ *
+ * - Write "Forkzero" in prose, never "ForkZero"
+ * - Logo renders as "FORK" (bold) + "ZERO" (thin) via Header component
+ *
+ * ## Do not
+ *
+ * - Hardcode color hex/hsl values — always use `colors.*`
+ * - Use `hoverLiftHandlers` — it is deprecated, use `useHoverLift`
+ * - Skip `data-fzui` on component roots — focus rings won't work
+ * - Set touch targets below 44px
+ */
+
+export { colors, shadows, radius, fonts, fontSizes, gradient } from './tokens'
 export {
   codeBlock,
   inlineCode,
@@ -10,6 +167,9 @@ export {
   LATTICE_LAYERS,
   LATTICE_EDGES,
   hoverLiftHandlers,
+  useHoverLift,
+  useReducedMotion,
+  injectGlobalStyles,
 } from './styles'
 export { Header } from './components/Header'
 export type { HeaderLink, HeaderProps, PoweredByHeaderProps } from './components/Header'

packages/ui/src/styles.ts

@@ -1,3 +1,4 @@
+import { useState, useEffect } from 'react'
 import type { CSSProperties, MouseEvent } from 'react'
 import { colors, fonts, shadows, radius } from './tokens'
 
@@ -65,8 +66,76 @@ export const LATTICE_LAYERS = [
 
 export const LATTICE_EDGES = ['supports', 'derives', 'satisfies'] as const
 
-// --- Hover lift helper ---
+// --- Global styles injection ---
 
+let globalStylesInjected = false
+
+export function injectGlobalStyles(): void {
+  if (typeof document === 'undefined' || globalStylesInjected) return
+  globalStylesInjected = true
+
+  const style = document.createElement('style')
+  style.setAttribute('data-fzui-global', '')
+  style.textContent = `
+[data-fzui] :focus-visible {
+  outline: 2px solid ${colors.accentBlue};
+  outline-offset: 2px;
+}
+@media (prefers-reduced-motion: reduce) {
+  [data-fzui] *,
+  [data-fzui] *::before,
+  [data-fzui] *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+`
+  document.head.appendChild(style)
+}
+
+// --- Reduced motion hook ---
+
+export function useReducedMotion(): boolean {
+  const [reduced, setReduced] = useState(() => {
+    if (typeof window === 'undefined') return false
+    return window.matchMedia('(prefers-reduced-motion: reduce)').matches
+  })
+
+  useEffect(() => {
+    const mq = window.matchMedia('(prefers-reduced-motion: reduce)')
+    const handler = (e: MediaQueryListEvent) => setReduced(e.matches)
+    mq.addEventListener('change', handler)
+    return () => mq.removeEventListener('change', handler)
+  }, [])
+
+  return reduced
+}
+
+// --- Hover lift hook ---
+
+export function useHoverLift(defaultShadow: string = shadows.md) {
+  const reducedMotion = useReducedMotion()
+  const [hovered, setHovered] = useState(false)
+
+  const style: CSSProperties =
+    hovered && !reducedMotion
+      ? { transform: 'translateY(-2px)', boxShadow: shadows.lg }
+      : { transform: 'translateY(0)', boxShadow: defaultShadow }
+
+  const handlers = {
+    onMouseEnter: () => setHovered(true),
+    onMouseLeave: () => setHovered(false),
+  }
+
+  return { style, handlers }
+}
+
+// --- Hover lift helper (deprecated) ---
+
+/**
+ * @deprecated Use the `useHoverLift` hook instead. This function mutates the DOM directly.
+ */
 export function hoverLiftHandlers(defaultShadow: string) {
   return {
     onMouseEnter: (e: MouseEvent<HTMLElement>) => {