# Prototype Craft Rules These rules sit on top of `docs/design/DESIGN_SYSTEM.md` and `docs/design/DESIGN_TOKENS.json`. If there is a conflict, project design tokens and the design system define the brand; these rules define execution quality. ## Anti-Slop Must-fix patterns: - Default Tailwind indigo or purple hex values used directly. - Two-stop trust gradients on hero sections. - Emoji inside headings, buttons, feature icons, or primary navigation. - Rounded cards with colored left-border accents. - Invented metrics such as "10x faster" or "99.9% uptime". - Filler copy such as lorem ipsum, sample content, placeholder text, or numbered product cards. - Repeated article/card bodies that only change the heading. Should-fix patterns: - Generic hero, feature, pricing, FAQ, CTA sequence when the screen brief calls for an app surface. - Placeholder image CDNs. - More than 12 raw hex values outside `:root`. - `var(--accent)` or `var(--primary)` used so often that everything competes for attention. - Decorative blob or wave SVG backgrounds. ## Color - Plan four layers before writing CSS: neutrals, one accent, semantic colors, and rare effects. - Use tokens or CSS custom properties. Avoid raw hex outside `:root`. - Keep accent use scarce: usually one primary CTA and one secondary signal per screen. - Do not introduce a second accent unless `DESIGN_TOKENS.json` declares it. - Normal text must meet WCAG AA contrast: 4.5:1 for body, 3:1 for large text and UI components. - Avoid pure black and pure white backgrounds; use tokenized near-black/near-white values when available. ## Typography - Use the font families and scale from the design system. - Cap visible type levels to a small, intentional set. - One element should be the dominant entry point in each visual region. - Use at least two hierarchy vectors for the dominant element: scale, weight, spacing, tracking, or alignment. - Body copy should stay readable, with a comfortable line length around 50-75 characters. - Button and label text should be concrete and action-oriented. - All-caps labels need positive tracking; display sizes need deliberate tighter tracking. ## Layout And Composition - Prefer product-specific structure over generic cards. - Use CSS Grid for real layout relationships, not only equal card rows. - Vary density by screen purpose: dashboards and tables may be tight; landing and decision areas need more air. - Do not place cards inside larger decorative cards. - Keep navigation and repeated controls stable across screens. - Use one decisive flourish: a proportion, type treatment, state surface, or interaction detail that supports the brief. ## State Coverage Every interactive list, table, card, form, search, or workflow surface needs visible handling for: - Loading - Empty - Error - Populated - Edge cases such as long text, missing optional fields, large result counts, or disabled actions Empty states need a headline, plain explanation, and action. Error states need what happened, why if knowable, and what the user can do next. ## Accessibility Baseline - One `

` per document. - Use semantic landmarks: `
`, `