Browse atoms

Accessibility After Thought

Treating accessibility as a final-step audit pass: design and build the UI based purely on visual mockups, then add `aria-label`, `role`, and `tabindex` afterwards to silence the audit warnings.…

Breaking Keyboard Flow

Re-implementing a `<button>`, `<a>`, `<input>`, or `<select>` as a custom `<div>` for styling reasons, without restoring the native keyboard semantics.…

Building drawers, dropdowns, modals, or accordions that respond exclusively to `onClick` mouse events — with no keyboard activation (Enter/Space), no escape-to-close, no focus trap, no ARIA disclosure semantics.…

Color Only Meaning

Communicating state — error vs success vs warning, valid vs invalid, online vs offline, required vs optional — through color alone, with no icon, label, or text differentiation.…

Hover Only Interaction

Building tooltips, hover cards, mega-menus, or row-action buttons that only appear on `:hover` or `mouseenter`, with no equivalent for keyboard focus or touch tap.…

Invisible Focus

A broader category than @community/anti-pattern-outline-suppression: the focus ring exists in CSS but is effectively invisible — too low contrast (1.…

Outline Suppression

The practice of suppressing browser-default focus outlines globally via CSS resets (`* { outline: none }` or `a:focus { outline: 0 }`) without providing custom focus indicators.…

Text In Image

Rasterizing important headlines, CTAs, prices, or product names directly into a JPG/PNG hero image instead of marking them up as HTML text. The text cannot be selected, copied, translated, screen-readered, or scaled.…

Tiny Touch Targets

Buttons, icon links, and tap targets sized below the WCAG 2.2 AA minimum of 24×24 CSS pixels — typically 16×16 or 20×20 icon-only buttons.…

Check Aria Label Required

Validates that interactive elements have an accessible name (computed via ARIA spec: aria-labelledby → aria-label → associated label → text → title).…

accessibility ↗ 1 · q4.0

Check Color Contrast Aaa

Evaluates contrast against WCAG 2.2 SC 1.4.6 Level AAA: 7:1 for normal text, 4.5:1 for large text (≥18pt or ≥14pt bold). Stricter than AA — recommended for prose-heavy products and a11y-first brands.

Check Contrast Aa

Evaluates whether the contrast ratio between foreground text color and background color meets WCAG 2.2 SC 1.4.3 Level AA. Large text (≥ 18pt regular or ≥ 14pt bold) requires 3:1; normal text requires 4.5:1.

Check Focus Visible

Checks that a keyboard-focusable element renders a visible, WCAG-compliant focus indicator when it receives keyboard focus.…

Check Focus Visible Styled

Validates that focus-visible styling is intentional and tokenized (uses CSS custom properties, has outline-offset or box-shadow spread, and is not suppressed by an unreplaced global outline:none reset).…

Check Form Label Associated

Validates that every visible form input (text, email, password, select, textarea, etc.) has a programmatically associated label: <label for>, wrapping <label>, aria-labelledby, or aria-label.…

Check Heading Hierarchy

Validates that heading levels (h1–h6) form a logical hierarchy: exactly one h1, no skipped levels (e.g. h2 → h4), and no empty headings. Required for screen-reader navigation (WCAG 2.4.6, 2.4.10).

Check Link Purpose Clear

Validates link text is descriptive enough to convey purpose without surrounding context (WCAG 2.4.4 / 2.4.9).…

Check Reduced Motion Required

Validates that any site using CSS animations/transitions also provides a @media (prefers-reduced-motion: reduce) block that effectively neutralizes motion (duration ≤ 0.01ms). Required for WCAG 2.2 SC 2.3.…

Check Skip Link

Validates that a skip-to-main-content link is present as the first focusable element in <body>, points to an existing target (#main, #content), uses skip-pattern text, and reveals on focus.

Check Touch Target Min

Validates that interactive elements (buttons, links, inputs, ARIA-interactive) meet WCAG 2.2 SC 2.5.8 minimum touch target size of 24×24 CSS pixels. Warns when below the 44×44 mobile recommendation.

Constraint Accessibility Aa Minimum

Every shipped page must meet WCAG 2.2 Level AA at minimum. Internal tools, prototypes, and feature flags do not relax this requirement once exposed to end users.

accessibility ↗ 6 · q4.0

Constraint Animation Pref Respected

All non-essential motion must respect `prefers-reduced-motion: reduce`. When the user has the OS-level setting enabled, decorative motion must be eliminated or replaced with an instant or sub-perceptual variant.

Constraint Content Language Declared

Every shipped HTML document must declare the primary content language via `<html lang='...'>`. Content blocks in a different language must be marked with `lang='...'` on the containing element.

Constraint Focus Trap Modal

Every modal dialog must implement a focus trap: keyboard focus must be sent into the modal on open, cycle within the modal on Tab / Shift+Tab, and return to the triggering element on close.

Constraint Mobile Touch Target 44px

Every touch-activated control must present a hit area of at least 44×44 CSS pixels on touch viewports. Visual rendering may be smaller, but the effective hit target (via padding or ::before expansion) must reach 44×44.

Constraint No Icons Without Label

Every icon-only interactive control must expose an accessible name via aria-label, aria-labelledby, or visually-hidden text. Decorative icons inside a labeled control are exempt.

Constraint Reduced Motion

All non-essential motion (transitions, CSS animations, JavaScript-driven animations) must be disabled or substantially reduced when the user has enabled `prefers-reduced-motion: reduce`.…

Counter Example Aria Bandaid

A modal dialog where the engineer added `role='dialog'`, `aria-label`, and `aria-modal='true'` after the audit complained — but kept the underlying `<div onClick>` for the close button, kept the heading as a `<p>` becaus…

Counter Example Div Button No Tabindex

A 'submit' button reimplemented as a styled `<div onClick>` because the team disliked the default `<button>` styles. No tabindex, no role, no Enter/Space handler.…

Counter Example Div Onclick Dropdown

A user account dropdown where the trigger is a `<div>` with `onClick`. Mouse users can open it; keyboard users cannot tab to it; screen reader users have no idea it's a menu.

Counter Example Hero Png Text

A landing-page hero where the gradient headline 'The future of finance.' and the 'Get started' button are both inside a single transparent PNG export from Figma.…

Counter Example Icon Button 24px

A modal close (×) button styled as a bare icon with no padding. The clickable area is 16×16 CSS pixels — well below the WCAG 2.2 AA 24×24 minimum and a third of the Apple/Material 44×44 recommendation.…

Counter Example Low Contrast Focus

A button focus state that uses a 1px light-gray outline. Technically a focus indicator exists, but at 1.4:1 contrast it is invisible at normal viewing distance.…

Counter Example Outline None

A widespread CSS anti-practice of globally suppressing focus outlines in base stylesheets or CSS resets, usually added because designers disliked the browser's default blue focus ring appearing on mouse clicks.…

Counter Example Status Color Only

An email input that signals invalid state purely by changing its border color to red. No icon, no error text on the field, no `aria-invalid`.…

Counter Example Tooltip Hover Only

An info-icon tooltip that explains a form field. On desktop hover it works; on mobile devices nothing happens; with keyboard focus the tooltip never appears.…

Example Radix Dialog

Radix Dialog implements full WAI-ARIA modal-dialog semantics: opens with focus moving to the first focusable element (or the explicitly-marked initialFocus), traps Tab cycling within the dialog, restores focus to the tri…

Example Radix Dropdown

Radix DropdownMenu opens on click or Space/Enter, supports ArrowUp/Down for item navigation, ArrowRight to open submenus, ArrowLeft to close back to parent, Home/End to jump to first/last, and type-ahead (typing 'p' jump…

Example Radix Tabs

Radix Tabs implements WAI-ARIA Authoring Practices for tabs: Tab/Shift+Tab moves focus into and out of the tablist; ArrowLeft/Right (or Up/Down with vertical orientation) moves focus between tabs WITHOUT activating; Spac…

Feedback A11y Audit V1

Accumulated execution feedback for @community/method-a11y-audit version 1.x. Summarizes observed success rates, common failure modes, and confidence adjustments derived from real audit runs.

A11y Audit

A comprehensive accessibility audit combining automated tool analysis (axe-core + Lighthouse) with structured manual checks for keyboard navigation, focus management, and screen reader compatibility.

Metric Contrast Ratio

The WCAG-specified luminance contrast ratio between a foreground color and a background color. Used to assess whether text and UI components meet accessibility thresholds.

Metric Target Size

The minimum interactive hit area for touch and pointer targets to be usable without accidental activation or difficulty. WCAG 2.2 SC 2.5.…

Provocation Accessibility By Default

@community/provocation-accessibility-by-default

Aria Label Required

Interactive elements that present no visible accessible name (icon-only buttons, icon-only links, image-only buttons) MUST carry a non-empty `aria-label` (or `aria-labelledby`, or visually-hidden text).…

Color Contrast

Enforces WCAG 2.2 color contrast requirements across all text and UI component elements in an HTML artifact. Covers SC 1.4.3 (text), SC 1.4.11 (non-text/UI), and SC 2.4.11 (focus ring).

accessibility ↗ 10 · q4.0

Color Contrast Aaa

Mission-critical body text — long-form articles, legal disclosures, healthcare information, financial figures — MUST meet WCAG 2.2 SC 1.4.6 Level AAA contrast: ≥ 7:1 for normal text and ≥ 4.5:1 for large text.…

Error Message Associated

Every form-validation error message MUST be programmatically associated with its field via `aria-describedby`, AND the field MUST set `aria-invalid='true'`.…

accessibility ↗ 6 · q4.0

accessibility ↗ 11 · q4.0

Focus Visible

Every keyboard-focusable interactive element MUST present a visible focus indicator that meets WCAG 2.2 SC 2.4.7 (Focus Visible) and SC 2.4.11 (Focus Not Obscured).…

accessibility ↗ 10 · q4.0

Form Label Associated

Every form control (`<input>`, `<select>`, `<textarea>`, custom widgets with role='textbox' / 'combobox' / 'listbox') MUST have a programmatically-associated label — via `<label for='id'>`, wrapping `<label>`, `aria-labe…

accessibility ↗ 10 · q4.0

Heading Hierarchy

Heading elements (`h1`–`h6`) MUST form a strict, gap-free hierarchy: exactly one `h1` per document, and each subsequent heading is at most one level deeper than its predecessor. Skipping levels (e.g.…

Keyboard Accessible

Enforces keyboard accessibility requirements: all interactive elements must be focusable, have visible focus indicators, and be operable with keyboard alone. Covers WCAG SC 2.1.1 (Keyboard), SC 2.4.3 (Focus Order), SC 2.…

Link Purpose Clear

Link text MUST be intelligible out of context — a screen-reader user listing all links on a page MUST be able to determine each link's destination from the text alone.…

Reduced Motion Required

Every CSS animation, CSS transition, and JS-driven motion MUST respect the user's `prefers-reduced-motion: reduce` setting.…

Skip Link

Documents with repeated header / navigation chrome MUST provide a 'skip to main content' link as the first focusable element. WCAG 2.2 SC 2.4.…

accessibility ↗ 8 · q4.0

Touch Target Min

All interactive targets (buttons, links, form controls, custom widgets) on touch surfaces MUST present a hit area of at least 44×44 CSS pixels, per Apple Human Interface Guidelines and WCAG 2.2 SC 2.5.…

Template Focus Ring

A baseline focus ring CSS template that satisfies WCAG 2.2 SC 2.4.11. Use as the foundation for per-component focus customization.

accessibility ↗ 7 · q4.0

Focus Ring

The visible outline or other visual indicator that marks which UI element currently holds keyboard focus, enabling sighted keyboard users to track their position in the interface.

Tool Axe Core

Deque's axe-core accessibility testing engine. Runs a comprehensive set of automated accessibility rules against an HTML document or DOM and returns violations, passes, incomplete (needs manual check), and inapplicable r…

Tool Axe Devtools

Deque's axe DevTools is the browser-based companion to axe-core, providing an interactive UI for running accessibility scans during manual QA and design review.…

Value Focus Outline Width

@community/value-focus-outline-width

Value Touch Target Min

@community/value-touch-target-min

fact @w3c

Wcag Contrast Aa

Normal text (< 18pt or < 14pt bold) must have a luminance contrast ratio of ≥ 4.5:1 against its background to meet WCAG 2.2 Level AA Success Criterion 1.4.3.

fact @w3c

Wcag Focus Contrast

WCAG 2.2 SC 2.4.11 (Level AA) requires that the focus indicator for a keyboard-focused UI component has a contrast ratio of ≥ 3:1 between the focused and unfocused states, and the focus indicator area must be at least as…

source @w3c

Source Wcag 22

The W3C normative standard for web content accessibility. WCAG 2.2 was published as a W3C Recommendation on 5 October 2023. It extends WCAG 2.1 with nine new success criteria, notably SC 2.4.…

Check Color Blacklist Brand

Scans CSS color declarations for blacklisted default brand colors (Tailwind blue-500/600, violet-600, indigo-600, Bootstrap #007bff) that signal generic 'AI slop' aesthetic.

aesthetic ↗ 2 · q4.0

Check Color Dark Mode Cascade

Validates that dark-mode color theming is implemented as a single token-layer cascade (light tokens at :root, dark overrides at :root.dark) rather than scattered dark: utilities or component-level color forks.

aesthetic ↗ 2 · q4.0

Check Color Oklch Required

Verifies that every color-bearing CSS property uses the oklch() function (directly or via a CSS custom property that resolves to oklch()). Rejects hex, rgb(), hsl(), and named colors.

aesthetic ↗ 2 · q4.0

Rpc As Rest

An API that uses HTTP+JSON but ignores REST semantics: verb-in-URL paths, status codes that don't match operations, GET with side effects, POST for everything.…

api-design ↗ 7 · q4.0

Http Method Semantics

RFC 9110 §9 defines HTTP method properties: GET (read; safe + idempotent + cacheable). HEAD (read metadata only; safe + idempotent + cacheable).…

api-design ↗ 7 · q4.0

Feedback Api Versioning Pain

Accumulated feedback from teams who shipped a public REST API and lived through 2+ major versions. Captures the pain points that did not appear in v1 design but emerged once the contract was real and consumers existed.

Cursor Pagination

Cursor-based pagination uses an opaque cursor (typically encoding a sort key + tiebreaker id) to mark a position in a sorted collection.…

Pagination First

List endpoints (GET /collection) MUST return paginated responses with: (1) a default page size (commonly 20–50, never unbounded); (2) a maximum page size enforced server-side (e.g.…

Resource Not Action

Every URL path is a noun phrase identifying a resource or collection. State changes occur via HTTP methods: GET (read), POST (create), PUT (full replace), PATCH (partial update), DELETE (remove).…

Scope Public Api

Defines applicability for atoms whose guidance applies only to public API surfaces — endpoints exposed beyond the controlling team.…

Idempotency Key

A client-supplied unique identifier (typically a UUID v4 or business-event id) attached to a non-idempotent request (POST, PATCH) that allows the server to safely deduplicate retries.…

Rest Vs Graphql

Choosing between REST (resource-oriented, HTTP-native) and GraphQL (query-oriented, schema-flexible) for a new API.…

Type Error Shape

Schema for an error response body in a JSON API. Based on RFC 9457 (Problem Details for HTTP APIs, July 2024) — the IETF-standard error format that supersedes RFC 7807.…

Type Pagination Cursor

Schema for a paginated response envelope. Carries the data array, has-more boolean, opaque cursor for fetching the next page, and optional total count.…

backend-engineering ↗ 5 · q4.0

Cache Strategy

The four canonical cache strategies trade off freshness, write latency, consistency, and operational complexity. Picking the right one depends on read/write ratio, staleness tolerance, and the cost of cache misses.

backend-engineering ↗ 5 · q4.0

Monolith Vs Microservices

Choosing between a single deployable monolith and a fleet of independently-deployed microservices. Microservices are oversold for early-stage products; monoliths are undersold for mature ones.…

consumer-brand ↗ 6 · q4.0

Voice Casual Warm

The voice used by friendly consumer brands. Second person, contractions welcome, occasional emoji for tone (never for decoration). Sounds like Mailchimp, Duolingo, Discord, Notion's onboarding.

Template Data Table Base

Foundational data table: sticky header, zebra-free row hover, sortable columns with aria-sort, pagination controls. Scoped headers for screen readers.

data-display ↗ 6 · q4.0

data-engineering ↗ 4 · q4.0

Batch Only Pipelines

Designing every data pipeline as a nightly (or hourly) batch job — typically Airflow + dbt + warehouse — when downstream use-cases require sub-minute freshness.…

data-engineering ↗ 5 · q4.0

Pii Tokenization

PCI-DSS, HIPAA, and GDPR Article 32 ('appropriate technical measures, such as pseudonymisation') all converge on the same architectural primitive: tokenization.…

data-engineering ↗ 5 · q4.0

Cdc Change Data Capture

Replicate a source-of-truth OLTP database to one or more downstream systems (data warehouse, search index, cache, replica) by tailing the database's transaction log rather than running periodic SELECT batches.

data-engineering ↗ 4 · q4.0

Idempotent Writes

Producers must attach a stable idempotency key (UUID, business-event-id, deterministic hash) to every write.…

data-engineering ↗ 4 · q4.0

Event Schema Versioning

Producer payloads must embed `schema_id` and `schema_version` (or use Confluent Schema Registry's wire-format magic byte + 4-byte schema id).…

Heuristic Review

A structured heuristic evaluation of a UI artifact against Nielsen's 10 usability heuristics. Produces a scored report with evidence-backed issues ranked by severity.

design-review ↗ 3 · q4.0

Step Apply Heuristics

@community/step-apply-heuristics

design-review ↗ 3 · q4.0

Step Load Artifact

@community/step-load-artifact

design-review ↗ 3 · q4.0

Voice Critical Mentor

The voice used when delivering design critique. Technically precise, direct without harshness, focused on specific fixable issues rather than general praise or vague negatives.…

design-review ↗ 2 · q4.0

Hardcoded Pixel Values

Writing raw pixel values (`padding: 16px`, `font-size: 14px`, `border-radius: 8px`) directly into component CSS instead of referencing CSS custom properties or design tokens.…

design-system ↗ 3 · q4.0

Magic Numbers

Numeric values that have no traceable origin: `padding: 13px`, `top: 47px`, `width: calc(100% - 73px)`, `transform: translateY(-2.5rem)`.…

design-system ↗ 3 · q4.0

Counter Example Hardcoded Pixel Padding

A typical card component CSS where every dimension — padding, margin, radius, gap — is written as a raw pixel literal. Looks fine in isolation but represents the failure to extract a token layer.

design-system ↗ 2 · q4.0

Counter Example Magic Number Padding

A header layout that uses off-grid pixel values and a `calc()` expression with a bare numeric constant. The values were nudged into place visually with no underlying system.

design-system ↗ 2 · q4.0

Provocation Design System As Product

@community/provocation-design-system-as-product

design-system ↗ 4 · q4.0

Tool Figma Tokens Plugin

Tokens Studio for Figma is the de-facto plugin for managing design tokens inside Figma and syncing them with code repositories (GitHub, GitLab, JSON files, Style Dictionary).…

Type Color Token Shape

Schema for a color token in a design system. A color token is more than its raw value — it carries semantic meaning, mode variants (light/dark), accessibility metadata (computed contrast), and provenance (primitive vs se…

Type Component Prop Shape

Schema for a design-system component's prop API. Captures variant + size + state dimensions, polymorphic 'as' support, accessibility props, and slot composition.…

Type Design Token

Schema for a design token — a named, typed design decision that is stored as data and consumed by design tools and code. Based on the W3C Design Tokens Community Group format (draft).

design-system ↗ 3 · q4.0

Type Spacing Scale

Schema for a spacing scale — the canonical set of distance values used for padding, margin, gap, and inset across the design system.…

developer-docs ↗ 6 · q4.0

Voice Dev Technical

The voice used in API references, SDK guides, and engineering documentation. Reference-friendly, low-hype, second-person imperative for tasks. Sounds like Stripe API docs, Tailwind docs, Anthropic docs, Postgres manual.

Template Modal Focus Trap

Modal dialog with proper focus trap, Esc to dismiss, backdrop click to dismiss, scroll lock, focus saved + restored to opener. Compatible without <dialog> element.

dialogs ↗ 11 · q4.0

editorial-magazine ↗ 6 · q4.0

Voice Poetic Literary

The voice used in literary magazine essays, Are.na profiles, Readwise highlights, and brand manifestos that aspire to last. Long-breath sentences, sensory specificity, restrained metaphor, deliberate rhythm.…

Constraint No Jquery Deps

New code must not introduce jQuery as a dependency. All DOM querying, event handling, and AJAX must use native browser APIs or the framework's built-in primitives.

engineering ↗ 1 · q4.0

enterprise-brand ↗ 7 · q4.0

Voice Brand Corporate

The voice used by large legacy enterprises in annual reports, investor decks, and About pages. Stable, aspirational, third-person, abstraction-heavy. Sounds like IBM, Salesforce, Oracle, SAP.…

Check Button Type Explicit

Validates that every <button> element declares an explicit type attribute (button | submit | reset). Buttons in forms default to 'submit' which causes accidental form submission — a common bug source.

forms ↗ 1 · q4.0

Check Error Message Associated

Validates that form-error messages are programmatically associated with their failing inputs via aria-describedby + role='alert' (or aria-live), and that aria-invalid='true' is set on the visually-errored input.

forms ↗ 3 · q4.0

Check Form Validation Inline

Validates that forms perform inline, field-level validation: each validatable input has an aria-describedby error region, validation triggers on blur/input (not just submit), and the form does not use window.…

forms ↗ 3 · q4.0

Template Form Validation

Inline form field validation using native :invalid + custom validity messages + aria-live error region. Zero JS libraries; works without JS for HTML-native types.

forms ↗ 12 · q4.0

Center Everything

Default-centering all text, cards, and sections as a safe layout strategy. Results in symmetrical layouts that feel templated, safe, and lacking in designed intentionality.

Gray On Colored Bg

Using achromatic gray text (oklch(X% 0 0)) on any non-white colored background. The gray appears washed-out, lifeless, and loses legibility because the chroma conflict between a chromatic background and achromatic text c…

Modal As Default

Using modal dialogs as the default mechanism for confirmations, forms, detail views, and settings — without considering less disruptive alternatives like inline expansion, side drawers, popovers, or dedicated pages.

Rounded Border Accent

Adding a thick colored border on a single side (left or top) of a rounded-corner card or callout box as a design accent treatment.…

Sparklines As Decoration

Tiny inline charts (sparklines, mini bar charts, trend indicators) placed in metric cards or dashboards to signal analytical depth, when the chart is too small to convey actual data insight and serves only as a visual so…

fact @anthropic-impeccable

Button Label Formula

Button labels must follow the verb + object pattern. Generic confirmations (OK, Submit, Yes, Cancel) are lazy and ambiguous — they force the user to reread the surrounding context to understand what the button will do.

fact @anthropic-impeccable

Dark Mode Not Inverted Light

Dark mode is not an inverted version of light mode. It requires independent design decisions on surface hierarchy (lighter surfaces = higher elevation), shadow removal, accent saturation reduction, text weight reduction,…

fact @anthropic-impeccable

Stagger Cap For Large Lists

CSS stagger animations must cap total stagger time. 10 items at 50ms/item = 500ms before the last element begins its entrance. For lists with many items, reduce per-item delay or cap the staggered item count.

pattern @anthropic-impeccable

Content Driven Breakpoints

Responsive breakpoints should be placed where the content actually breaks — not at device-convention widths.…

pattern @anthropic-impeccable

Multi Dimension Hierarchy

Strong visual hierarchy requires combining at least two of the five hierarchy dimensions simultaneously on primary elements: size, weight, color contrast, position, and surrounding whitespace.…

pattern @anthropic-impeccable

Undo Over Confirm

For reversible destructive actions (delete, archive, remove), apply the action immediately and show an undo toast with a countdown window.…

Ai Slop Test

The final quality bar for any AI-generated interface is whether a viewer would immediately assume 'AI made this.' A distinctive interface makes someone ask 'how was this made?' — not 'which AI made this?'

Cards Not Required

Cards are a container of last resort, not a default layout primitive. Spacing and alignment create visual grouping naturally — most contexts that ship cards would be better served by typography and whitespace alone.

Font Pairing Contrast

A second typeface is only justified when it provides genuine contrast on multiple axes (structure, personality, or proportion) — similar-but-different pairings create visual tension without hierarchy.…

Perceived Performance

Perceived performance — how fast an interface feels — is as important as measured performance. The 80ms threshold, preemptive transitions, and optimistic UI are perceptual engineering tools, not just nice-to-haves.

Tinted Neutrals

Neutrals (grays, near-blacks, off-whites) should carry a subtle tint of the brand hue. Even a chroma of 0.01 in OKLCH creates subconscious cohesion that pure achromatic grays cannot achieve.

Unforgettable One Thing

Every interface needs one differentiating element — the single thing a viewer will remember. Intentional design means knowing what that one thing is before writing the first line of code.

Animate Transform Opacity Only

CSS transitions and animations MUST target only `transform` and `opacity`. Animating layout properties (width, height, padding, margin, top, left, border-width) triggers browser layout recalculation on every frame, causi…

Empty State Teaches

Empty states must do three things: (1) briefly acknowledge the empty condition, (2) explain the value the user will get by filling it, (3) provide a clear, specific action to begin.…

Exit Faster Than Entrance

Elements leaving the viewport or DOM should animate out in approximately 75% of the duration used for entering.…

No Redundant Copy

Every word in a UI must earn its place. Heading text must not be restated in the first paragraph. Button labels must not repeat what the heading already says.…

Single Orchestrated Entrance

A single orchestrated page-load sequence with staggered reveals produces more delight than micro-interactions scattered across the interface.…

Template Accordion Grid Rows

CSS-only accordion expand/collapse using grid-template-rows: 0fr → 1fr transition instead of height: 0 → auto. No JavaScript measurement required, no layout-forcing animation, GPU-composited friendly.

Template Dark Mode Surface Hierarchy

Dark mode elevation hierarchy uses progressively lighter surface colors to indicate depth — the inverse of light mode which uses shadows.…

Template Font Loading Fout Fix

A CSS @font-face pattern that uses `font-display: swap` with a metric-adjusted fallback font to minimize layout shift when the custom font loads.…

Template Opentype Features

CSS declarations to enable common OpenType features that most developers overlook: tabular numerics for data alignment, ordinal/diagonal fractions for recipe/measurement display, small caps for abbreviations, and ligatur…

Ai Generated Ui

The predictable visual fingerprint shared by all unconstrained AI-generated UIs: Inter font + purple-to-blue gradient + rounded-2xl everywhere + shadow-lg on every card + hero→3col→testimonials→CTA layout — immediately r…

Ai Slop Aesthetics

Generic, predictable visual choices — Inter/Roboto/Arial fonts, purple gradients on white backgrounds, context-free cookie-cutter components — that mark a UI as unthinkingly AI-generated because they represent the statis…

Burying Frequent Actions

Placing actions that belong to core user workflows several menu levels or clicks deep in sub-menus, overflow menus, or secondary panels — forcing repeated multi-step navigation overhead on every session for the app's mos…

Cherry Picking Evidence

Selecting only the research data points that support a predetermined design direction while ignoring contradictory signals — creating false confidence in a chosen solution while real problems go unaddressed.

Clear Form On Failure

Resetting or clearing an entire form when only a single field fails validation, forcing users to re-enter all previously filled data after a minor mistake.

Cramped Ui

Overly tight spacing that impairs content scanning and makes tap targets touch or overlap, failing both readability and touch-device accessibility.

Custom Cursor A11y

Custom cursor implementations that apply cursor: none globally or add trailing/lerp animation create five distinct accessibility failures: semantic cursor loss, click hot-zone misalignment, vestibular motion harm (prefer…

Decorative Spinning

Applying infinite CSS rotate animation to logos, icons, decorative shapes, or background elements purely for visual interest — spinning adds no information, loops forever triggering motion sickness risk, and violates pre…

Deep Branching Nav

Building 3+ level nested folder navigation when flat tags, filters, or faceted search would better support findability — forcing users to memorize exact paths to items that conceptually belong in multiple categories.

Fake Trust Signals

Using fabricated social proof numbers, stock photo testimonial avatars, badges on every section, logos without permission, linked compliance cert badges, or vague guarantee copy — all patterns that neutralize or reverse …

Generic Error Text

Displaying 'An error occurred', 'Something went wrong', or 'Please try again' without explaining what failed, why, or what the user should do next.

Icon Only Expansion Triggers

Hiding secondary or advanced options behind unlabeled icon buttons — a caret (›), chevron (⌄), ellipsis (⋯), or gear (⚙) — with no visible text label, leaving new users unable to discover what the button reveals without …

Ignoring Negative Experiments

Treating a negative or inconclusive A/B test result as a failure to hide rather than a learning to document, causing the same losing hypothesis to be retested repeatedly.

Infinite Marquee No Pause

An infinite CSS marquee/ticker strip with no pause-on-hover, no pause-on-focus, and no prefers-reduced-motion stop — fails WCAG 2.1 criterion 2.2.2 (Pause, Stop, Hide) for any animation lasting more than 5 seconds.

Ios Fullscreen Spinner

Showing a full-screen ProgressView (or activity indicator overlay) that blocks all interaction while content loads.…

Ios Hamburger Menu

Using a hamburger (three-line) icon to reveal a hidden side-drawer navigation menu on iOS. This pattern violates iOS navigation conventions and severely reduces feature discoverability.

Ios Ignore Safe Area

Using .ignoresSafeArea() on text labels, buttons, or any interactive element causes content to be clipped under the Dynamic Island, status bar notch, or home indicator on modern iPhones.

Ios Non Dismissable Modal

Presenting a sheet or full-screen modal with no cancel button and swipe-to-dismiss disabled, trapping the user until they complete a forced step.

Ios Stacked Modals

Presenting a second .sheet or .fullScreenCover on top of an already-presented sheet, creating multiple layered modal contexts.

Multi Change Experiment

Bundling two or more independent design changes into a single experiment variant makes it impossible to attribute outcome to any individual change — a fundamental confounding error.

No Bounce Everything

Applying spring overshoot or bounce easing (cubic-bezier Y > 1, e.g. cubic-bezier(0.34,1.56,0.…

Overloaded Screen

Cramming many unrelated actions, decisions, or form sections onto a single screen within a user flow — presenting everything at once instead of guiding users through focused, single-purpose steps.

Thin Weight Body

Using font-weight 100–300 for body prose or UI labels at 16px and below causes illegibility on low-DPI displays, fails WCAG contrast requirements at lower contrast ratios, and reads as fragile or insubstantial to most us…

Vanity Metrics

Declaring experiment success based solely on metrics that do not reflect actual user value — page views, clicks, session duration, impressions — without verifying that user outcomes improved.

Check Ios Bold Text Support

Verifies that custom-rendered text in an iOS app responds to the Bold Text accessibility setting.…

Check Ios Hig Compliance

Verifies that an iPhone app meets the 20 most critical Apple Human Interface Guidelines covering layout, navigation, typography, accessibility, color, gestures, modality, permissions, and system integration.

Check Ios Increase Contrast

Verifies that custom colors in an iOS app provide higher-contrast variants when the Increase Contrast accessibility setting is active.…

Constraint Card Grid Gap

Card grids must use gap: 16px (gap-4) minimum for dense dashboards and gap: 24px (gap-6) for content layouts — never gap: 8px or less, so cards read as discrete units rather than a merged surface.

Constraint Distinctiveness Mandate

Every designed artifact must pass the AI-slop test before ship: show the interface to someone who knows design tools and say 'AI made this.…

Constraint Focus Indicator Min Size

A focus indicator must enclose the component with a perimeter area of at least (component perimeter × 2 CSS pixels) and achieve 3:1 contrast against every adjacent color, meeting WCAG 2.2 SC 2.4.11 Focus Appearance (AA).

Constraint Ios Onboarding Max 3

Onboarding flows must be at most 3 pages, must always be skippable, and must defer sign-in / account creation until after the user has experienced core app value.

Constraint Ios Reserved Gestures

Apps must never attach gesture recognizers that intercept the four iOS reserved system gestures: swipe from left edge (back navigation), swipe down from top-left (Notification Center), swipe down from top-right (Control …

Constraint Ios Text Min 17pt

No text on iOS may be smaller than 11pt; body text should be 17pt. Hardcoded sizes must not go below 11pt; use semantic text styles to scale naturally with Dynamic Type.

Constraint Ios Touch Target 44pt

Every touch-activated control must present a hit area of at least 44×44pt on iOS. Visual rendering may be smaller, but the effective tap target must reach 44×44pt.

Constraint Monospace Tabular Numerics

Numeric data in tables, dashboards, financial UIs, and metric cards MUST use tabular-numeral rendering (`font-variant-numeric: tabular-nums`) — NOT a monospace typeface — unless the typeface is itself monospace for other…

Constraint Motion Page Load Budget

Page-load entrance animations must complete within 800ms total — hero in ≤ 600ms at 250-400ms per element, stagger cap of 70ms × 8 items = 560ms — to avoid blocking perceived interactivity.

Constraint No Account Existence Disclosure

Auth error messages must never reveal whether a given email or username exists in the system — use a single neutral message regardless of the failure reason.

Constraint No Content Flashing

Content must not flash more than 3 times per second — the WCAG 2.1 Success Criterion 2.3.1 (Level A) threshold above which photosensitive seizures can be triggered.

Constraint Section Spacing

Section vertical padding must use py-20 sm:py-32 (or clamp(80px, 10vw, 128px)) with max-w-6xl mx-auto px-4 sm:px-6 container — never arbitrary margins between sections.…

Constraint Shallow Navigation Depth

Navigation hierarchy depth must stay at 3 levels or fewer — pass: ≤3, warn: 4, block: ≥5.

Constraint Text Color Three Shades

A complete UI text color system MUST use exactly three lightness tiers — primary (foreground, weight 500+, highest contrast), secondary (muted-foreground, ~60–70% lightness relative to primary), and tertiary (disabled/pl…

Constraint Three Viewport Breakpoints

Responsive layouts must define distinct behavior for at least three viewport ranges — narrow (< 640px mobile), medium (640px–1023px tablet/small desktop), and wide (≥ 1024px desktop) — ensuring the mainstream device spec…

Constraint Typography Weight Blacklist

font-weight 100, 200, and 300 are BANNED for body text (≤ 20px) and primary UI labels; font-weight 900 is BANNED for body text. Permitted body/label weights are 400 (regular), 500 (medium), and 600 (semibold).…

Constraint Visual Fingerprint Uniqueness

A designed product must have a unique visual fingerprint — a set of at least 3 specific, non-default design choices that make it immediately recognizable as distinct from both AI-generated output and competitor products …

Example Accessible Chart

A production-ready accessible area chart using Recharts and React. Demonstrates: figure/figcaption ARIA wrapping, sr-only description paragraph, aria-hidden chart SVG, prefers-reduced-motion gate on animations, a hidden …

Example Gallery Cta Sections

17 curated CTA section screenshots from Land-book Pro, tagged by pattern type and persona lean. CTA sections are inflection points in the scroll narrative — they ask the visitor to make a decision.…

Example Gallery Feature Sections

13 curated feature section screenshots from Land-book Pro, tagged by pattern type and persona lean.…

Example Gallery Full Landings

20 curated full-page landing screenshots from Land-book Pro, tagged by pattern type and persona lean.…

Example Gallery Hero Sections

20 curated hero section screenshots from Land-book Pro, tagged by pattern type and persona lean. Use to find the right hero shape for a given register.…

Example Gallery Pricing Sections

20 curated pricing section screenshots from Land-book Pro, tagged by pattern type and persona lean.…

Example Gallery Testimonial Sections

16 curated testimonial section screenshots from Land-book Pro, tagged by pattern type and persona lean. Testimonial sections are the primary vehicle for social proof on a landing page.…

Example Linear Kbd Shortcuts

Linear's issue tracker exposes nearly every action through a command palette (Cmd/Ctrl+K) and single-key shortcuts (e.g. 'C' to create issue, 'P' to set priority).…

Ai Fingerprint Detection

A trained eye can identify AI-generated UI in under 5 seconds by checking: (1) Is the font Inter or Plus Jakarta Sans? (2) Is the primary color ~270° hue (purple/violet/indigo)? (3) Is rounded-2xl applied to everything? …

Ai Palette Convergence

Unconstrained LLM agents converge on: Indigo-600 or Violet-500 for hero backgrounds, Blue-500 for CTAs on white, Slate-700 for body text, and identical Tailwind default tokens across every project — producing 'AI slop' s…

Animation Curve Anticipation

Anticipation is one of Disney's 12 principles of animation: before a character jumps, they crouch. In UI, an anticipation curve applies the same principle: before a button moves right, it briefly moves left.…

Animation Curve Overshoot

An overshoot curve has a control point with Y value > 1 (or < 0), which causes the animated property to temporarily exceed its target value before settling.…

Animation Mood Emotional Mapping

Users perceive motion character before they consciously notice it. A 1200ms ease-out entrance feels editorial; a 250ms spring feels app-like; a 80ms linear press feels precise.…

Anthropic Brand Typography

Anthropic brand design mandates Poppins (weight 600–700) for all heading levels at 24pt+ with Arial as system fallback, and Lora (weight 400) for body text at 16–18px with Georgia as system fallback; the pairing communic…

Anti Vibe Coded Fingerprints

Vibe-coding produces its own predictable aesthetic: dark background + neon accent (#00FFAA, #FF00FF, or cyan #06B6D4) + frosted glass panels + every card animated with spring-back bounce + hero with radial gradient blob …

Aria Live Politeness

aria-live='polite' waits for the screen reader to finish the current utterance before announcing a region update, while aria-live='assertive' interrupts immediately — use polite for status messages and assertive only for…

Border Radius Platform

iOS system UI uses 26–44px radius on cards and prominent surfaces (superellipse/squircle geometry), intentionally warm and approachable.…

Component Anatomy Three Layers

The three-layer anatomy — container / content / interaction affordances — is a structural fact of UI components, not a design preference.…

Fintech Number Display

Fintech UI typography follows a strict numeric hierarchy: the primary metric (account balance, total transaction, price) must be 3–4× larger than the smallest supporting metric; every numeric context must use tabular-num…

Ios Background Hierarchy

iOS defines three system background color levels — systemBackground, secondarySystemBackground, tertiarySystemBackground — that automatically adapt to light and dark mode to create visual depth in grouped layouts.

Ios Button Style Hierarchy

iOS defines four button style roles with distinct visual weights: .borderedProminent for primary CTA, .bordered for secondary actions, .borderless for tertiary inline actions, and role: .…

Ios Sf Symbols Rendering Modes

SF Symbols support four rendering modes — monochrome, hierarchical, palette, and multicolor — each with a distinct visual purpose and SwiftUI symbolRenderingMode API.

Ios System Gesture Vocabulary

iOS defines a standard set of touch gestures with established, consistent meanings across all apps: tap (select/activate), long press (context menu/preview), horizontal swipe (delete/archive/back), vertical swipe (scroll…

Motion Vocabulary

UI motion divides into three distinct categories with different implementation paths: (1) Transitions — CSS transition property, fire on property change, reverse on removal, best for hover/focus/toggle; (2) Animations — …

Opportunity Cost Of Defaults

Each of the five AI-slop signal categories (color, typography, radius, shadow, layout) is an independent differentiation opportunity.…

Pwa Display Mode Taxonomy

Web App Manifest display mode values, ordered from most to least app-like:

Pwa Installability Criteria

PWA install prompt (beforeinstallprompt / Chrome install button) fires only when ALL four are true:

Required Interaction States

Six states are required for every interactive component:

Semantic Html Element Taxonomy

HTML5 semantic elements by category:

Transitions Vs Animations

CSS transitions and CSS animations are not interchangeable. A CSS transition fires when a CSS property value changes and automatically reverses when the trigger is removed — making it correct for hover, focus, and toggle…

Ui Component Library Reference

Study component libraries for their design decisions and a11y implementation. Extract patterns; don't blindly install them unless the task specifically requires it.

Variable Font Axes

A variable font is a single font file that contains a design space defined by named axes; CSS accesses axes via `font-variation-settings` or high-level properties (`font-weight`, `font-stretch`, `font-optical-sizing`, `f…

Feedback Stripe Redesign 2024

Post-hoc analysis of Stripe's late-2023/2024 dashboard and marketing-site refresh.…

Animation Format Decision

A decision tree for choosing between Pure SVG+GSAP, Rive, and Lottie based on interactivity requirements, designer toolchain, bundle budget, and file-size constraints.

Anti Ai Slop Checklist

A structured pre-ship audit of the five AI fingerprint categories — color, typography, layout, visual effects, motion — that distinguishes intentionally designed output from statistical-average AI output.

Brand Distinctiveness Test

A 5-question audit that tests whether a design communicates specific brand identity rather than generic AI-generated output — applied before any public launch or design review.

Design Md Extraction

A protocol for extracting a structured design.md file from any existing UI, reference gallery screenshot, or design brief — producing a reusable design system document that can guide AI-agent frontend generation.

Design Qa Pre Ship

A structured checklist for reviewing UX flows, design consistency, accessibility, and content quality before releasing any user-facing feature — covering the 10 categories most commonly skipped in AI-generated outputs.

Gallery Research

A 6-step protocol for extracting reusable design patterns from gallery sites (land-book.com, godly.website, mobbin.com) — replacing passive browsing with structured pattern extraction that produces actionable tokens.

Persona Fingerprint Test

A rapid 3-question audit to verify that a generated UI has the correct visual fingerprint for its declared persona — ensuring the persona brief was actually enacted rather than just named.

Research Finding Structure

Frame every UX research finding as three linked statements: the observed behavior, the underlying need driving it, and the design opportunity it reveals.

Rule Authoring Checklist

Nine-point verification checklist for any new or updated design rule file — ensures every rule has a single purpose, clear activation condition, concrete examples, and anti-patterns before it is merged.

Adaptive Images Dark Mode

@community/pattern-adaptive-images-dark-mode

Airbnb Signature Marketing

The eight signature design patterns that define Airbnb's visual language: three-layer shadow lift, Rausch Red as singular accent, warm near-black, circular navigation controls, generous radius scale, Cereal VF weights, p…

Autocomplete Combobox

A text input that filters and surfaces a popup listbox of suggestions as the user types, allowing free-text entry and selection. Used for tag pickers, address inputs, mention pickers, and search-as-you-type.

Blog Article Layout

A long-form reading layout with constrained measure (60-80ch), confident typographic hierarchy, optional drop cap on the lede, sticky table of contents on desktop, and metadata block (author, date, read time, tags).

Border Radius By Persona

@community/pattern-border-radius-by-persona

Border Radius Decision

@community/pattern-border-radius-decision

Breadcrumb Trail

A horizontal sequence of links showing the path from a root location to the current page (e.g., Workspace > Project > Issue). Provides hierarchical wayfinding and one-click jump-up navigation.

Button Hierarchy Web

A 5-variant (primary, secondary, outline, ghost, destructive) × 3-size (h-8/h-9/h-10) button system with loading states, icon-only variants sized to 44×44 CSS px on mobile, and CVA class-variance-authority composition pa…

Button Press Feedback

按钮按下瞬间 scale(0.97-0.98) + 颜色加深 + 80-120ms 极短反馈，模拟物理按键的'按下去'感。iOS / Linear / Arc / Vercel 标志性触感，让点击从'click'变成'按下'。

Calendar Grid

A 7-column x 5-6 row grid showing a calendar month, with each day cell hosting event chips. Supports keyboard navigation between days, multi-day event spans, and view-switching between Month / Week / Day.

Card Component

A bounded surface using border + border-radius: var(--radius) with 3 internal zones (header p-6, content p-6 pt-0, footer px-6 py-4), nested corner radius formula (inner = outer − padding), and interactive lift via trans…

Chart Grid

Pattern for embedding responsive Recharts area/bar charts inside a dashboard card, including a period-range toggle in the header and a stat-footer below the chart. Based on shadcn/ui ChartContainer conventions.

Chart Responsive Container

Charts MUST fill their parent's width via a ResponsiveContainer wrapper, never use a fixed pixel width. The only fixed dimension is height, chosen from a standard scale.…

Checkout Summary

A sidebar panel during checkout listing line items, subtotal, tax, shipping, discounts, and total. Sticky on desktop so the total is always visible while users fill the form; collapsible on mobile.

Code Splitting

Load JavaScript modules only when needed using dynamic import() — splitting bundles by route (load page code when navigated to) or by interaction (load heavy component code when user triggers it).

Color Dark Mode Pairing

@community/pattern-color-dark-mode-pairing

Color Persona Mapping

@community/pattern-color-persona-mapping

Color Scale Decision

@community/pattern-color-scale-decision

Command Palette

A full-screen or centered modal overlay triggered by a keyboard shortcut (typically Cmd/Ctrl+K) that provides a searchable, keyboard-navigable list of all application commands.…

Command Palette Modal

A specific implementation of a command palette as a centered modal dialog (not full-screen, not inline) — a 480-640px-wide floating card overlaid on a scrim, opened with Cmd/Ctrl+K.…

Container Queries

Size components based on their container width using container-type: inline-size and @container name (min-width: Npx) rules, enabling components to adapt layout independently of the viewport — essential when the same com…

Dashboard Animations

Three precise CSS animation patterns used in admin dashboards: sidebar collapse transition, accordion/collapsible content expand, and button press micro-interaction. All should respect prefers-reduced-motion.

Dashboard Data Table

An interactive data table for dashboard pages: sticky muted header, hover-state rows, sortable columns with chevron indicators, search + categorical filter toolbar above, and paginated rows. Powered by TanStack Table.…

Dashboard Grid

A responsive grid of self-contained metric cards (KPIs, sparklines, lists, charts) covering a workspace. Each card is independently sized and reorderable; the grid reflows by viewport using auto-fit columns.

Dashboard Header

A compact 48px sticky topbar for admin dashboards. Contains: sidebar toggle (left), breadcrumbs or search bar (center/left), and a right-side cluster of notifications, theme toggle, and user avatar.…

Dashboard Layout

Structural composition for admin dashboards: a fixed sidebar on the left, a sticky topbar, metric cards at the top of the main content area, a chart section, and a data table below. Extracted from two open-source Next.…

Dashboard Sidebar

A collapsible left navigation sidebar for admin dashboards. Three modes: expanded (256px), icon-only (48px), and mobile drawer (288px).…

Data Table Dense

A high-density tabular grid optimized for scanning hundreds of rows: 28-36px row height, monospace numerals, sticky header, sortable columns, and inline-editable cells.…

Date Range Picker

A dual-month calendar popover for selecting a start and end date in one flow, with preset shortcuts (Last 7 days, This month, Custom). Used in analytics filters, booking systems, and report selectors.

Doc Page

A standardized layout for documentation pages that supports navigability at scale: fixed left sidebar navigation, scrollable content column with max-width 680–720px, and a right-column table of contents that tracks scrol…

Doc Toc

A sticky right-column table of contents that auto-generates from h2/h3 headings in the main content area and uses IntersectionObserver to highlight the currently visible section as the user scrolls.

frontend-design ↗ 15 · q4.0

Drawer Side

A panel that slides in from the right (or left) edge of the viewport, overlaying or pushing content. Used for detail inspectors, edit forms, and mobile nav menus where context-with-task is more important than full focus.

Dropdown Multilevel

A two-level dropdown menu where top-level items with children reveal a fly-out submenu panel positioned inline-end, using aria-haspopup=menu + aria-expanded on the parent item, and ArrowRight/ArrowLeft keyboard navigatio…

Empty State

A purposeful screen shown when a list, table, or workspace has no data, combining a friendly illustration or icon, an explanatory headline, body copy, and a primary CTA that helps the user create their first item or reco…

frontend-design ↗ 0 · q4.0

Enterprise Global Frame

A stable global navigation frame (top bar or side rail) that persists structurally across all products and modules in a multi-product enterprise application.…

Expandable Disclosure

A button with aria-expanded + aria-controls=PANEL_ID toggles the visibility of a collapsible region panel, using <details>/<summary> native HTML or a custom implementation with CSS transition: max-height on the controlle…

Fade In On Load

页面或区块加载完成时让元素从 opacity 0 渐入到 1，可选叠加微小的 translateY 位移。最基础的进场动效，几乎所有 marketing 页 / dashboard 卡片都用。让内容'显现'而不是'闪现'。

Feature Flag Rollout

A staged rollout strategy using feature flags to release new UI features to incrementally larger user segments — starting with internal users, then a small percentage of real users, then full rollout — with a kill switch…

Features Grid

Three features section layout variants — card grid (md:grid-cols-2 lg:grid-cols-3 gap-8), horizontal divider rows (editorial anti-card), and alternating flex-row/flex-row-reverse image layout — extracted from shadcn-land…

File Upload Dropzone

A bordered drop region that accepts files via drag-drop, click-to-browse, or paste. Shows per-file progress, validates type/size before upload, and surfaces errors inline.

Fintech Hero Amount Card

A card component that establishes the primary financial metric as the visual focal point. The hero amount uses clamp(2.5rem, 6vw, 4rem) display font, tabular-nums, and a decorative gold radial gradient corner.…

Fintech Number Display

Typography, formatting, and hierarchy rules for displaying financial amounts, KPI metrics, and change indicators in fintech and SaaS dashboards — where numbers are the primary signal and must command visual weight and co…

Gantt Timeline

A two-pane view with a left task list and a right horizontal timeline of bars representing task duration, dependencies, and progress. Used for project planning where dependencies and overlap matter.

Gradient Mesh Engine

@community/pattern-gradient-mesh-engine

Hero 3 Layouts

Three battle-tested hero section layouts extracted from open-react-template (4.6k★), shadcn-landing-page (1.9k★), and next-saas-starter (1.…

Hero With Demo

A landing-page hero combining a left-side text block (eyebrow + H1 + sub + dual CTA) with a right-side interactive product demo (video, animated mockup, or actual embedded UI).…

Hover Lift

Card / button 悬浮时上抬 1-2px + 阴影加深，传达可点击的物理直觉。Linear / Vercel / Stripe 风格的标志性微交互，让静态界面在指针靠近时变得'活的'。

Inline Validation

Validates form fields at the field level, displaying success/error messaging adjacent to each input rather than only on submit. Fires after the user signals they are 'done' with the field (blur or after a debounce).

Interaction States

Every interactive element must implement all 8 distinct states — default, hover, focus, active, disabled, loading, error, and success — with visually distinguishable styles for each.

Ios App Shortcuts Siri

Expose key app actions to Siri, Spotlight, and the Shortcuts app by implementing AppShortcutsProvider with AppIntent, phrases, shortTitle, and systemImageName — allowing users to invoke the action without opening the app…

Ios Haptic Feedback

Pair visual state changes with haptic feedback for significant user actions using UIFeedbackGenerator. Haptic confirmation closes the feedback loop — the user feels the device acknowledge their action, not just sees it.

Ios Inset Grouped List

The .insetGrouped style is the standard iOS visual treatment for grouped scrollable lists.…

Ios Large Title Nav

Top-level views use large navigation bar titles that collapse smoothly to inline (standard) size as the user scrolls down.…

Ios Live Activities

Use ActivityKit Live Activities for real-time, time-bound events (delivery ETAs, sports scores, timers) surfaced on the lock screen and in the Dynamic Island's compact, expanded, and minimal layouts.

Ios Location Button

Use CoreLocationUI LocationButton with .currentLocation or .sendMyCurrentLocation title variant to grant one-time location access for a single action, bypassing the standard When-In-Use authorization flow.

Ios Navigation Stack

Use NavigationStack with a NavigationPath binding and .navigationDestination(for:) modifiers for type-safe, programmatically-navigable push/pop hierarchies in iOS 16+.

Ios Sheet Presentation

Present a .sheet or .fullScreenCover for a self-contained, discrete task; use .presentationDetents([.medium, .…

Ios Skeleton Loading

Show placeholder view structures matching the final content layout while async data is fetching, using .redacted(reason: .placeholder) in SwiftUI or custom grey-bar shapes — replacing them when real data arrives.

Ios Tab Bar Top Level

Use a persistent bottom tab bar with 3–5 items (SF Symbol icon + label) for top-level section navigation on iPhone, providing direct access to each section and preserving state independently per tab.

Ios Thumb Zone

Place primary call-to-action controls in the lower half of the screen (thumb zone) where the thumb naturally rests in a one-handed grip, keeping destructive or infrequent actions in the upper, harder-to-reach zones.

Ios Widgets Glanceable

Provide WidgetKit widgets for frequently-checked app data surfaced on the home screen or lock screen; use AppIntent-powered Button/Toggle within widgets for one-tap interactive actions in iOS 17+.

Kanban Board

A horizontal lane-based board where each column represents a workflow status (e.g., Backlog / In Progress / Done) and each card is a draggable work item.…

Kbd Shortcut Chip

Render keyboard shortcuts as an array of individual <kbd> elements (one chip per key, split on spaces) rather than a single <kbd> blob — the space-delimited shortcut string convention from cmdk's Raycast demo enables per…

Landing Footer

4–6 column responsive footer grid using grid-template-columns: 2fr repeat(4, 1fr) on xl — brand col gets double width — with link group styling, social icons row (flex gap-4 mt-4, aria-label required), newsletter form, a…

Landing Navigation

Two landing nav structural variants — floating rounded bar (open-react-template: top: 1rem, border-radius: 1rem, backdrop-filter: blur(12px), h-14) and classic sticky full-width bar (shadcn: top: 0, backdrop-filter: blur…

Landing Page Sections

Seven structural section patterns for landing pages — hero (centered/split/asymmetric), features (card-grid/divider/alternating), pricing (3-column with scale(1.…

Log Viewer Virtualized

A monospace, line-numbered scrollable viewer that virtualizes (only renders visible rows) for log streams of 100k+ lines. Supports follow-tail, level filtering, regex search, and click-to-pin a line.

Metric Card

A single KPI card with label, large value, optional trend badge, and a secondary element chosen from a variation toolkit. Arranged in a responsive 4-column container-query grid.…

Micro Interaction Css

Five reusable pure-CSS micro-interaction recipes: button press (asymmetric timing), checkbox stroke-dashoffset check, toggle switch, input focus ring, and form shake on invalid submission.

Modal Confirm

A small centered dialog that interrupts the user to confirm a destructive or consequential action (delete, archive, sign out).…

Modal Non Blocking

A non-blocking overlay panel — implemented as a slide-in sheet (position: fixed; inset-inline-end: 0) or anchored popover — that does NOT trap focus and allows interaction with the page behind it, using role=complementar…

Motion Forms

Form animation patterns — validation shake on error, input focus glow, and success feedback on submit — that communicate state changes functionally rather than decoratively, using Motion.dev or CSS transitions.

Motion Loading

Loading animation hierarchy: skeleton pulse (1.5s ease-in-out opacity 0.4→0.7 loop) > progress bar > stagger dots (0.6s, 0.…

Motion Microinteraction

Microinteraction animation system: hover lift (transform 200ms cubic-bezier(0.16,1,0.3,1)), button press scale(0.…

Motion Modal

Modal animation choreography: backdrop fades in at 200ms ease-out while panel slides from translateY(12px) to 0 at 300ms cubic-bezier(0.16,1,0.3,1) — exit reverses in 150ms; body scroll locked during open lifecycle.

Motion Navigation

Navigation animation patterns: tab indicator sliding via Motion.dev layoutId with spring stiffness:400/damping:30, hamburger menu expanding at 250ms cubic-bezier(0.16,1,0.…

Multi Step Flow Feedback

Each step in a multi-step flow must carry a clear step label, current position indicator, logical step order, and per-step validation feedback before advancing.

frontend-design ↗ 13 · q4.0

Multi Step Wizard

A linear sequence of form steps presented one at a time with a top progress indicator (e.g., '2 of 5 - Account'). Each step validates before advance; users can go back without losing input.

Native Html Interactive

Prefer native HTML interactive elements — <details>, <dialog>, <input popover>, <meter>, <progress>, inert attribute — over custom JavaScript implementations for accordions, modals, tooltips, and progress indicators.

Optimistic Update

A UI pattern where mutations (toggle, like, edit, move) reflect in the UI immediately — before the server confirms — and reconcile (or revert with toast) on response.…

Page Load Choreography

First-visit page load animation sequence: prevent FOUC with initial hidden state, stagger-reveal content blocks after paint, and skip the animation on return visits using sessionStorage.

frontend-design ↗ 12 · q4.0

Page Transition

路由切换时旧页面 fade + 微 slide-out，新页面 fade + slide-in，整个过程 200-300ms。让 SPA 路由跳转有'空间连续性'，不会在切换瞬间感觉断帧。Linear / Notion / Arc 风格。

Persona Component Mapping

A cross-persona lookup table showing how the same HTML component renders under 6 distinct aesthetic personas — Brutalist, Editorial, Tokyo Minimal, Warm Institutional, Dense Pragmatist, Swiss Modernist — enabling rapid f…

Plan Comparison Table

A wide feature-by-feature comparison matrix with rows for capabilities and columns per plan, using checkmarks, X marks, or specific values per cell. Used below the tier cards on pricing pages for users who need detail.

Posthog Signature Marketing

The seven signature design patterns that define PostHog's visual language: hidden orange hover flash, sage/olive anti-corporate palette, hand-drawn hedgehog illustrations, opacity-based button hover, bold IBM Plex Sans h…

Pricing Section

Standard 3-column pricing layout with a featured card using transform: scale(1.05) + border-top: 3px solid var(--accent) + shadow-xl, monthly/annual toggle with React key remount animation, and exact CSS for card differe…

Pricing Tiers Toggle

A 3-column pricing layout (typically Free / Pro / Team) with a monthly/annual billing toggle that updates all prices simultaneously, an emphasized recommended tier, and a feature checklist per column.

Progressive Disclosure

A UX pattern that initially shows only the most important information or options, revealing additional detail on user demand.…

Pwa Service Worker Offline

Register a service worker from the main thread; inside the worker, cache critical assets on the install event and intercept fetch requests to serve cached responses when the network is unavailable.

Replicate Signature Marketing

The seven signature design patterns that define Replicate's visual language: pill-radius absolutism (9999px everywhere), 128px manifesto closer, explosive orange-to-magenta hero gradient, dotted-underline links, AI-gener…

Resource Hints Preconnect

Use <link rel='preconnect'> for critical third-party origins, <link rel='preload'> for critical first-party assets, and <link rel='dns-prefetch'> as a fallback for lower-priority origins — placed in <head> before any sty…

Scroll Reveal

元素滚动进入视口时触发 fade + slide 入场，长页面（landing page、blog post、portfolio）让分段内容感觉'一步步揭露'而不是页面 paint 完所有就位。用 IntersectionObserver 或 CSS animation-timeline: view() 实现。

Shadow Elevation System

Five-level CSS shadow elevation system using OKLCH-tinted colors and the Hobday blur rule (blur = 2× y-offset): --shadow-xs through --shadow-xl mapped to CSS custom properties, with dark-mode fallback via surface lightne…

Sidebar Collapsible

A persistent left-rail navigation panel that can collapse from a labeled-icon state (~240px) to an icon-only state (~56px), preserving navigation while reclaiming canvas space.…

Skeleton Loader

Placeholder shapes (gray bars, rectangles, circles) that mimic the final content layout while data is loading. Reduces perceived wait time and prevents layout shift compared to spinners or empty space.

Skeleton Shimmer

骨架屏的'光泽掠过'动画——一条比背景稍亮的渐变带从左到右循环平移 1.2-1.6s。让骨架屏从'静态灰块'变成'明确正在加载'的强信号。Facebook / YouTube / Stripe loader 标志样式。

Slide Up Reveal

内容从下方 16-24px 处上滑同时 opacity 渐入，比纯 fade 更强烈的'到达'感。Hero section、card grid、modal 内容进场最常用。Apple / Stripe / Notion 风格。

Stagger Reveal

List / grid 子项错位入场——每项延迟 50-100ms 开始 fade + slide。比同时入场更有节奏感，让用户的眼睛沿入场顺序扫描内容。Framer / Linear / Stripe dashboard 标志性手法。

Sticky Header On Scroll

A page or section header using position: sticky; top: 0 that adds a shadow or border-bottom on scroll (via IntersectionObserver sentinel), optionally hides on scroll-down and reveals on scroll-up to maximize content view…

Subscription Status

A settings-page card summarizing the user's current plan, billing cycle, next charge date, payment method on file, and seat usage, with primary actions (Upgrade, Manage seats, Update payment) and a secondary Cancel link.

Svg Noise Grain Texture

SVG feTurbulence filter encoded as a data-URI pseudo-element overlay that adds film grain to flat digital UI — making surfaces feel physical and editorial without image assets. Uses position:fixed for scroll performance.

frontend-design ↗ 14 · q4.0

Tab Bar Bottom

A fixed-position horizontal bar at the bottom of a mobile viewport containing 3-5 top-level destinations as icon+label tabs. Optimized for thumb reach and persistent navigation in mobile-web and PWA shells.

Table Of Contents Sticky

A right-rail (or left-rail) navigation listing the article's H2/H3 headings, sticking to the viewport during scroll.…

Testimonials Section

Three testimonial section layouts — masonry grid with useMasonry() hook (open-react-template), CSS columns: 3 masonry (shadcn), and Swiper carousel with pauseOnMouseEnter: true autoplay (next-saas-starter) — with exact c…

frontend-design ↗ 12 · q4.0

Toast Stack

Transient, non-blocking notifications anchored to a screen corner (typically bottom-right) that auto-dismiss after 4-6 seconds. Stacks newest on top with up to 3 visible; older toasts collapse or rotate out.

Tooltip Keyboard

A small floating label revealed on hover OR keyboard focus that supplements an icon-only or terse control with explanatory text. Critical for discoverability of icon buttons in dense UIs.

Top Nav Mega

A top horizontal nav whose items expand into a multi-column flyout panel grouping product, solution, resource, and developer links with icons and short descriptions. Used by marketing sites with broad surface area.

Trust Badge Row

Small pill badges communicate tangible trust attributes (security, compliance, reliability) inline without interrupting the reading flow. Placed directly below or beside the primary hero CTA.

Trust Logo Strip

A row of company logos communicates social proof through brand recognition. Logos are grayscale at 0.45 opacity at rest, full-color on hover. Positioned below the fold after initial interest is established.

Trust Security Cert

Compliance badges (SOC 2, ISO 27001, GDPR, PCI DSS) in a centered flex row at 0.65 opacity with 30% grayscale. Positioned at the bottom of the page where procurement teams look.

Trust Signal Components

Five trust signal component types for landing pages — badge rows, logo strips, social proof numbers, testimonial micro-quotes, and security certification badges — each placed at the specific conversion objection it resol…

Trust Social Proof Numbers

Large, scannable numbers in a responsive grid make abstract claims concrete. Uses tabular-nums, display font at clamp(1.75rem, 4vw, 2.5rem), and muted labels. Placed mid-page after feature sections.

Trust Testimonial Micro

A single inline testimonial — one sentence, one 36px avatar, one attribution — with a 3px primary-color left border accent. Placed contextually beside pricing to answer 'has someone like me succeeded?'

Tx Blocknote Block Editor Core

Notion-style block editor composition using BlockNote v0.x (MPL-2.0): a single BlockNoteDefaultUI renders up to eight opt-in floating UIs (FormattingToolbarController, SuggestionMenuController for '/', GridSuggestionMenu…

Tx Blocknote Drag Handle

BlockNote hover-gutter drag handle pattern: a six-dot MdDragIndicator button that is simultaneously a drag source (draggable={true}) and a dropdown menu trigger, with sideMenu.…

Tx Blocknote Nested Indent

BlockNote smart-Enter keyboard handler for nested list items: when a bulletListItem, numberedListItem, checkListItem, or toggleListItem is empty and Enter is pressed, convert the block back to a paragraph (exit the list)…

Tx Cmdk Fuzzy Search

cmdk (pacocoursey/cmdk) fuzzy search scoring constants from command-score.ts: six weights that encode specific UX priorities for match ranking — SCORE_CONTINUE_MATCH=1.0, SCORE_SPACE_WORD_JUMP=0.…

Tx Dnd Kit Drop Indicator

dnd-kit (@dnd-kit/abstract) drag feedback pattern: DragOverlay ghost that follows the cursor with a +N count badge for descendants, CSS data-shadow='true' for source lift (scale 1.…

Tx Dnd Kit Kanban Columns

dnd-kit (@dnd-kit/abstract) multi-list kanban board: both columns and items registered as useSortable with distinct type/accept tags, CollisionPriority.…

Tx Dnd Kit Nested Tree

dnd-kit nested tree drag with depth projection: flattens recursive tree to FlattenedItem[] (depth, parentId, id), projects drag depth from pointer transform.…

Tx Liveblocks Avatar Stack

Liveblocks AvatarStack component (Apache-2.0): reads useOthers() and useSelf() presence, dedupes by userId first (falling back to connectionId for anonymous users) using a Map, caps visible avatars at max=3 with a +N ove…

Tx Liveblocks Floating Comment

Liveblocks FloatingThread component (Apache-2.0): comment thread anchored to any trigger via Radix Popover with updatePositionStrategy='always' to survive scroll, onInteractOutside guard to prevent emoji picker / nested …

Tx Liveblocks Live Cursor

Liveblocks Cursor + PresenceCursor pattern (Apache-2.0): arrow SVG with fill='currentColor' inheriting from --lb-cursor-color CSS custom property, presence stored as normalized 0-1 coordinates multiplied by ResizeObserve…

Tx Liveblocks Sync Badge

Liveblocks connection-status pill pattern (Apache-2.0): React component writes useStatus() string to data-status attribute; CSS [data-status='connected'] selectors drive all state styling — color, pulsing ::before ping a…

Ux Experiment Hypothesis

A structured sentence template for writing testable UX experiment hypotheses: 'If we change X for Y users, we expect Z metric to move in direction because reason' — ensuring every experiment has a defined independent var…

Virtual List Rendering

Virtualized list rendering technique: only mount DOM nodes for visible rows plus a small overscan buffer, using scrollTop, itemHeight, and containerHeight to compute the visible window.…

frontend-design ↗ 26 · q4.0

Persona Toss

Korean fintech super-app precision: Pretendard on #FAFAFA page with near-ink #3C3C3C text, single saturated accent #721FE5 reserved for active/selected states only, hero metrics at 48px/24px 2:1 ratio, and card shadows a…

Border Radius Aesthetic

Border-radius is a design decision that communicates product personality — it must be chosen intentionally based on persona and brand, not accepted as a framework default.…

Clear User Mental Model

Every interface must make three things immediately clear: what the user can do here, where they currently are in the product structure, and what happens if they take each visible action.…

Color System Foundation

Every Prime-guided project must use a three-layer color architecture — Primitive (OKLCH values), Semantic Scale (12-step functional scale), and Application Token (CSS custom properties) — and no layer may be skipped.…

Commit Bold Aesthetic

Choose and fully commit to a specific, extreme aesthetic direction before writing any implementation code.…

Consistent Cross Platform Mental Models

Core concepts, terminology, and user mental models must remain consistent across all platforms of a product — when users switch from web to mobile to desktop, they should not have to learn a new vocabulary for the same f…

Design Philosophy Before Canvas

Before executing any canvas art or static design, first write a visual philosophy document (aesthetic movement, form, color, scale, composition, hierarchy) — then execute the art using it as an unambiguous foundation.…

Error Prevention And Recovery

Interfaces should prevent mistakes by design first (constraints, confirmation, input validation) and provide clear, actionable recovery paths when errors do occur anyway.…

Evidence Not Aesthetics

Design decisions affecting user behavior, conversion, or accessibility must be grounded in evidence (user research, A/B data, analytics, heuristics) — not in aesthetic preference alone.…

Generative Creative Not Utility

AI-generated design artifacts should be evaluated on creative and aesthetic quality standards — not merely on whether they function correctly.…

Implementation Complexity Match

Implementation complexity must match the aesthetic vision: maximalist designs require elaborate layered code; minimalist designs require restraint and precision — both are hard in different ways.

Intentional Gradient

Gradients must serve one of three defined purposes — mesh atmosphere (depth behind content), linear accent wash (directional energy on surfaces), or radial accent glow (ambient light around a CTA) — and must interpolate …

frontend-design ↗ 13 · q4.0

Landing Page Sections

A high-converting landing page composes 7 distinct section types in varied structural sequence — hero, features, pricing, testimonials, navigation, footer, and spacing — never repeating the same layout consecutively.…

Navigation Scope Taxonomy

Every navigation component belongs to exactly one of three scopes: (1) Global — spans the entire product and appears on all pages; (2) Local — scoped to a single section or feature area, appears within that context only;…

Prove Not Prevent Ai Slop

The goal of anti-slop guidelines is to prove distinctive quality — not merely to prevent the worst defaults. A design that avoids all slop signals but makes no positive aesthetic statement has still failed.…

Refactor When Evidence Shows It

Refactor a design decision only when evidence (usability test, analytics, A/B result, error log) specifically shows the current implementation is failing — not because the code looks improvable, trends have shifted, or a…

Security Copy

Security messaging in UI must satisfy three criteria: (1) Specific — name exactly what is at risk ('your password' not 'your account'); (2) Actionable — tell the user exactly what to do right now ('Click the link in your…

Shared Visual Language

Color tokens, typography roles, spacing scale, and iconography must come from a shared design token system used consistently across all platforms, so the product feels visually unified even when interaction patterns diff…

Single Direction Aesthetic Bet

Make one bold aesthetic bet per project and commit fully. Two aesthetic directions in a single product create incoherence; zero aesthetic direction creates generic output.…

Subtle Conceptual Reference

The subject of canvas art, poster design, or visual illustration should be woven as a quiet conceptual thread into form, color, and composition — not illustrated literally.

Taste As Engineering

Aesthetic taste in design is an engineering discipline: it is learnable, reproducible, testable, and decomposable into specific decisions.…

Tone Calibration

UI copy tone must shift to match the emotional stakes of the interaction while clarity remains constant — calm and neutral for routine actions, honest and supportive (never alarming) for errors and high-stakes flows.

Typography Hierarchy

Preserve clear typographic hierarchy so headings dominate body, and captions or metadata remain distinct but legible.…

Ui Differentiation Memorability

Before building any UI, identify the one element a user will remember — and execute it with precision. Undifferentiated UIs have no recall value.

Unexpected Spatial Composition

Use unexpected spatial arrangements — asymmetry, overlap, diagonal flow, or grid-breaking elements — to avoid predictable layouts that blend into the statistical mean of AI-generated UI.

Vertical Rhythm

Spacing between sections must be greater than spacing between items within a section. Differentiated spacing communicates containment and hierarchy to users without requiring explicit borders or dividers.

Visual Hierarchy Action Distinction

Primary and secondary actions must differ visually across at least two dimensions — typically fill (solid vs transparent/outline), color emphasis (accent vs neutral), and font weight (semibold vs normal) — so users can i…

White Space As Design Element

White space (negative space) is an active design element, not wasted space. Generous padding around elements communicates quality, focus, and hierarchy.…

Provocation Anti Anti Aesthetic

@community/provocation-anti-anti-aesthetic

Provocation No Perfect Symmetry

@community/provocation-no-perfect-symmetry

Access Change Consequence Disclosure

When a user's access level changes (role assignment, permission upgrade or downgrade, account access modification), the UI must display a before/after delta and explicitly label any irreversible consequences before the u…

Accessibility First Class

Accessibility must be treated as a core product requirement from the design phase onward — not a post-launch audit — because retrofitting WCAG AA compliance after launch costs 10–100× more than building it in, and inacce…

Actionable Error Messages

Error and success messages must be actionable and tied to the specific context in which they appear — telling the user what happened AND what to do next.…

Active Voice In Ui Copy

Write all UI labels, status messages, confirmations, and instructions in active voice with an explicit subject (user or system). Passive voice constructions are prohibited.

Align Changes To Findings

Proposed design changes must be cross-referenced against documented pain points, validated patterns, and known success metrics before finalizing direction.…

Aria Current Page

The active navigation link must carry aria-current='page' so screen readers announce 'current page' and give keyboard users orientation within the site structure (WCAG SC 2.4.8, ARIA 1.2 aria-current attribute).

Aria Label In Name

When an interactive element has visible text, its accessible name computed by aria-label or aria-labelledby must include that visible text as a substring, so voice-control users can activate it by speaking what they see …

Aria Native First

Use a native HTML element before applying ARIA roles, states, or properties — native semantics are more robust, require less maintenance, and have broader assistive technology support than ARIA overrides (ARIA in HTML sp…

Auth Flow Reversibility

Every step of sign-in, sign-out, password reset, account recovery, and MFA enrollment flows must have a clear back, cancel, or recovery path — users must never be able to reach a dead end in an authentication flow.

Autocomplete Attributes

Form inputs collecting personal data (name, email, phone, address, credit card) MUST carry a valid HTML `autocomplete` attribute token so browsers and password managers can autofill correctly and meet WCAG 1.3.5.

Backgrounds Atmospheric

Page and section backgrounds must not default to a single flat solid color; use atmosphere-creating techniques — gradient meshes, noise textures, tinted layered gradients, grain overlays, or geometry — to signal delibera…

Brand Accent Shapes

Non-text decorative shapes, icons, and graphic elements must use only the brand's defined accent colors (not the primary action color or semantic status colors), cycling through them in rotation to maintain visual intere…

Brand Color Primary Only

High-chroma brand colors and the primary action color must appear only on primary interactive actions (CTAs, active states, focus rings, progress indicators) and key highlights — never on decorative elements, backgrounds…

Canvas Elements Within Boundaries

Every text, graphic, and visual element in a canvas art output (.pdf or .png) must remain within canvas boundaries with proper margins. No elements may be clipped by the canvas edge. No two elements may overlap.…

Canvas Visual Text Ratio

Static art and poster outputs must allocate approximately 90% of their composition to visual design and at most 10% to text. Outputs with text above 25% of composition area are rejected — they are documents, not art.

Chart Never Alone

Every chart requires paired context. Required pairings by chart type: Area chart → period toggle (1W/1M/3M) in card header + 2-3 stat items below a border-t in the card footer.…

Collapse Multi Column Mobile

Any multi-column layout (grid-template-columns with 2+ columns, or flex-direction: row with multiple siblings) must reflow to a single column at narrow viewports — preferably mobile-first via grid-template-columns: repea…

Color Hue Selection

A palette must have hue spread of at least 120 degrees between primary and accent colors; primary and accent must differ in chroma by at least 0.…

Color Scheme Meta Tag

Every web page that implements dark mode must include `<meta name='color-scheme' content='light dark'>` in <head> so the browser themes native UI controls (scrollbars, form inputs, select menus, checkboxes) to match the …

Composable Layout Primitives

Structure every view using named layout primitives — Stack (single-axis flex), Grid (two-dimensional CSS grid), Cluster (wrapping inline-flex for tags/chips), Sidebar (one fixed + one fluid column) — rather than arbitrar…

Confirm Before Applying Theme

Never apply a visual theme to an artifact until the user has explicitly confirmed their theme choice by naming a specific theme or number in the same exchange.…

Consistent Design Token Scale

All spacing, typography, and border-radius values must come from a defined token scale — never ad-hoc numeric literals. Every value in the codebase must be traceable to a named token or scale step.

Consistent Form Action Placement

Primary and secondary form actions (submit, cancel, back) must use clear, consistent labels and be placed in a predictable position throughout a product, so users build reliable spatial memory for action buttons.

Consistent Product Terminology

The same concept or product entity must use the same word or phrase everywhere in the product. Using different words for the same thing in different screens (e.g.…

Content Based Breakpoints

Define responsive breakpoints at the specific widths where your actual content degrades — lines become too long, columns become too narrow, text overflows — rather than at named device categories (mobile/tablet/desktop).…

Correct Input Type

Form inputs must use the HTML `type` attribute that matches the expected data (e.g.…

Cross Field Validation

Validation rules that span multiple form fields (e.g. password-confirm match, date-range overlap, conditional required fields) must run on form submission rather than per-field blur, and surface a grouped error summary a…

Cross Platform A11y Parity

Each platform must implement the accessibility conventions native to that platform — touch targets ≥ 44×44pt on iOS/Android and full keyboard navigation on desktop — because ignoring platform-specific assistive-technolog…

Cross Platform Accessibility Parity

Each platform must implement the accessibility conventions native to that platform — web requires ARIA and keyboard navigation, iOS requires Dynamic Type and VoiceOver labels, Android requires TalkBack support — and acce…

Cross Platform Flow Step Consistency

Multi-step flows (onboarding, checkout, account setup) must present the same steps in the same logical order across all platforms, even if visual grouping or layout differs per platform.

Cross Platform Handoff Points

Points in a user flow where users may transition from one platform to another (e.g.…

Css Logical Properties

Replace physical CSS directional properties (margin-left, margin-right, padding-left, padding-right, border-left, border-right, left:, right:) with logical equivalents (margin-inline-start, margin-inline-end, padding-inl…

Culturally Neutral Copy

UI copy must avoid idioms, culturally specific metaphors, or humor that may not translate across cultures or languages.…

Current Location Indicator

Every navigation component (global nav, sidebar, tab bar, breadcrumb) must visually mark the active item with a distinct treatment AND set aria-current='page' (for page-level) or aria-current='true' (for section-level) o…

Custom Component Aria Role

Any custom component replacing a native HTML widget must carry the matching ARIA role attribute. Dropdowns need role=menu + role=menuitem. Modals need role=dialog + aria-modal=true.…

Data Viz Accessible

SVG and canvas charts must expose a descriptive aria-label on role='img' that states the data trend, never rely on color as the sole encoding channel, provide a screen-reader text alternative (sr-only table or summary), …

Design Decisions Cite Research

When usability studies, interviews, surveys, or analytics exist, every design proposal must explicitly reference the supporting evidence — naming at least one data source (test, interview finding, funnel metric) in its r…

Design Md Front Matter

Every design.md file must begin with YAML front matter declaring at minimum: project name, persona archetype, and 3-5 aesthetic keywords. A design.…

Design Qa Definition Of Done

Design and UX quality review is a required gate — not optional — for any user-facing feature. A story or ticket is not done until the design QA checklist is completed and signed off.

Destructive Action Differentiation

Destructive actions (delete, remove, reset, revoke) must never share the same visual style, color treatment, or spatial grouping as safe actions.…

Dialog Affordance Required

Every modal dialog must provide an explicit visible affordance to close it — a close button (×), a labelled 'Cancel' or 'Dismiss' button, or both.…

Embed Images With Context

Images embedded in documentation, blog posts, or content pages must always include contextual framing — at minimum an alt text describing what is shown AND a caption or surrounding copy explaining why the image is releva…

Empty State Recovery

Empty states caused by filters, search queries, or permissions (zero-results empty) must include a recovery affordance — a button or link that removes the filter, clears the search, or explains how to gain access.…

Enterprise Scalable Naming

Naming conventions for labels, section names, and entity identifiers in enterprise information architectures must be unique and unambiguous when seen from the global (top) level — no two levels of the IA may use the same…

Explicit Ratio Not Magic Number

Spacing, sizing, and typographic scale values must derive from an explicit ratio (1.25, 1.333, 1.5, or a defined 4px/8px base grid) — not from magic numbers chosen ad-hoc. Every value must have a traceable derivation.

Explicit Trade Off Disclosure

When any design or implementation decision degrades UX quality, information architecture clarity, or accessibility compliance, the trade-off must be named explicitly in the design rationale or PR description — with the s…

Factual Not Aspirational

UI copy must make factual claims about what the product actually does — not aspirational claims about what it might do for the user. Claims without supporting evidence are prohibited in UI interfaces.…

Fieldset Legend

Logically related input groups (radio buttons, checkboxes, or multi-field address blocks) must be wrapped in `<fieldset>` with a `<legend>` that names the group, so screen readers announce the group context before each o…

Flow Ordering Mental Model

Multi-step flows must sequence steps in the order users expect based on domain conventions.…

Font Feature Settings

Display and body fonts MUST enable OpenType features at the CSS level: at minimum `font-feature-settings: 'kern' 1, 'liga' 1` globally; fintech/data UIs MUST add `'tnum' 1, 'lnum' 1`; brand or editorial contexts SHOULD a…

Font Loading Fout Foit

Every `@font-face` declaration for a custom web font MUST include `font-display: swap` to prevent FOIT (Flash of Invisible Text — up to 3 s of blank text) and control FOUT (Flash of Unstyled Text) by showing the fallback…

Font Self Host

Production web fonts MUST be self-hosted as WOFF2 files under the project's origin, not loaded from Google Fonts CDN or third-party font services, to eliminate third-party DNS latency (50–200 ms per domain), comply with …

Font Weight Not Style

Font weight variation MUST be expressed via `font-weight` values (400, 510, 700) using a typeface that ships those weights — never via `font-style: oblique` or browser-synthesized faux-bold (`font-weight: bold` on a sing…

Freeze Design Decisions

Once a design decision has been shipped to production users and validated with evidence, freeze it.…

Functional Image Alt

An <img> that is the sole content of a <button> or <a> element must have alt text describing the action the control performs, not the visual appearance of the image, so screen readers announce an actionable label (WCAG S…

Ghost Button

Ghost buttons (transparent background + visible border) are a secondary action style only — never use ghost buttons as the primary CTA on a page.…

Gradients Justified Only

Gradients, shadows, and color palettes must not be generated ad hoc; every gradient must be sourced from documented tokens or a named pattern type (mesh atmosphere, linear accent wash, or accent glow), and must not appea…

Group Related Form Fields

Related form fields must be visually and semantically grouped — using section headings, helper text, and proximity — so users can comprehend field relationships and navigate the form without cognitive overload.

Gsap Now Free

In any project with a JS bundler and node_modules, GSAP is the default animation engine for anything beyond simple :hover CSS transitions. The paywall that previously justified CSS-only defaults has been removed.…

Heading Hierarchy Logical

Heading levels must progress sequentially (h1 → h2 → h3) mirroring visual hierarchy. Skipped heading levels (e.g. h1 → h3) are forbidden.

Hover Focus Animation Parity

Every CSS animation or transition applied on :hover must also be applied identically on :focus-visible — keyboard users must receive the same visual motion feedback as mouse users, not just a static outline.

Ia Group By User Tasks Not Org

Navigation groupings must reflect user mental models — organized around the tasks users do, the objects they operate on, or the domains they think about — not around internal team ownership boundaries, engineering module…

Image Explicit Dimensions

Every <img> element MUST carry explicit width and height attributes matching the image's intrinsic dimensions to prevent Cumulative Layout Shift (CLS) during page load.

Image Lazy Loading

Images that are not visible in the initial viewport MUST use loading='lazy' to defer their network fetch; above-the-fold images MUST use loading='eager' (the default) and should use fetchpriority='high' for the LCP image…

Informative Image Alt

Images that convey meaning or information must have descriptive `alt` text explaining their content or function; decorative images must use `alt=''` to hide them from assistive technology.

Inline Loader Placement

Loading indicators MUST appear immediately adjacent to the content being fetched — replacing or overlaying only the affected region — not as a global full-page spinner disconnected from the triggering action.

Intl Api Locale Formatting

Dates, times, numbers, currencies, and list conjunctions must be formatted using the JavaScript `Intl` API (Intl.DateTimeFormat, Intl.NumberFormat, Intl.ListFormat) rather than hard-coded locale-specific strings.

Ios 8pt Grid

All spacing and sizing values in iOS layouts must align to multiples of 8pt; use 4pt only for fine adjustments.

Ios Alerts Critical Only

Reserve UIAlertController alerts for critical information that requires an immediate decision; prefer at most 2 action buttons, never more than 3.

Ios Att Compliance

Show the ATT (App Tracking Transparency) prompt via ATTrackingManager.requestTrackingAuthorization before collecting any cross-app tracking data, and provide full app functionality to users who deny.

Ios Context Menu Redundant

Every action in a context menu must also be accessible through a visible button, swipe action, or toolbar item — a context menu must never be the only path to an action.

Ios Custom Color Dark Variants

Every custom color in an iOS app must define both Any Appearance and Dark Appearance variants in the asset catalog (.xcassets) so it adapts automatically when the system appearance changes.

Ios Custom Font Dynamic Type

Custom fonts must be scaled with Dynamic Type by registering them via UIFontMetrics.scaled(for:) in UIKit or Font.custom(_:relativeTo:) in SwiftUI, anchored to a semantic text style.

Ios Dynamic Type Reflow

Layouts must reflow gracefully at Dynamic Type accessibility sizes (up to ~200% scale) so that essential text is never clipped or truncated.

Ios Dynamic Type Semantic

Use semantic system text styles for all text; never specify hardcoded point sizes.

Ios Flexible Layout

Layouts must adapt from iPhone SE (375pt width) to iPhone Pro Max (430pt width) without hardcoded widths or fixed dimensions.

Ios Gesture Alternatives

Every custom gesture must have an equivalent action accessible via a visible button or menu — no action may be gesture-only.

Ios Immediate Action Acknowledgment

Acknowledge every user tap immediately with a visible state change — disable the button, show an inline spinner, or change label text — even while the underlying operation is still running.

Ios Interruption Handling

Observe scenePhase changes and save state on background, pause on inactive, and resume cleanly on active — ensuring no user progress is lost across system interruptions.

Ios Launch Screen Match

The launch screen must visually replicate the app's initial view rather than showing a logo or branding screen.

Ios No Forced Account

Allow users to access and explore core app functionality without requiring sign-in or account creation; gate only features that are genuinely meaningless without an account (purchases, sync, social interactions).

Ios No Override Swipe Back

Custom gesture recognizers must not intercept the system swipe-from-left-edge back navigation gesture; scope any custom horizontal DragGesture to avoid the leftmost 20pt edge.

Ios Permission In Context

Trigger permission requests at the point of use, not at app launch.

Ios Permission Pre Prompt

Show a custom explanation screen describing why the permission is needed and what benefit the user gains before triggering the system permission dialog.

Ios Preserve Navigation State

Persist and restore scroll position, selected tab, search text, filters, and any user-entered state across navigation transitions and app foregrounding.

Ios Reduce Motion

Disable or replace decorative animations with a simple crossfade when the Reduce Motion accessibility preference (UIAccessibility.isReduceMotionEnabled) is active.

Ios Safe Area Insets

Never place interactive or essential content under the status bar, Dynamic Island, or home indicator; respect UIEdgeInsets from safeAreaInsets / safeAreaLayoutGuide at all times.

Ios Semantic System Colors

Use iOS semantic system colors — Color.primary, Color.secondary, Color(UIColor.systemBackground), Color(UIColor.label), etc. — rather than hardcoded hex or named colors for all text and backgrounds.

Ios Sf Symbols Animations

Use the .symbolEffect() or .contentTransition(.symbolEffect) modifiers for SF Symbol state changes instead of conditional if/else swaps between symbol names.

Ios Sf Symbols Tab Bar

Tab bar icons must use SF Symbols; the selected tab displays the filled variant (e.g., 'house.fill') and unselected tabs display the outline variant (e.g., 'house').

Ios Sf Symbols Weight Scale

Set SF Symbol weight to match adjacent text weight; use the .small, .medium, or .large scale variants (imageScale) instead of explicit point sizes to size symbols relative to their text context.

Ios Share Sheet

Use the iOS system share sheet — ShareLink in SwiftUI or UIActivityViewController in UIKit — for sharing content rather than custom share UIs.

Ios Sign In With Apple

Include Sign in with Apple as the first authentication option whenever any third-party sign-in provider is offered; this is required by App Store Review Guideline 4.8.

Ios Single Accent Color

Set a single app-wide tint/accent color applied uniformly to all buttons, links, and toggles; avoid using multiple competing accent colors across the interface.

Ios Spotlight Indexing

Index key app content using CSSearchableItem with a CSSearchableItemAttributeSet so it is discoverable from iOS Spotlight search without opening the app.

Ios Tab Bar Always Visible

The tab bar must remain visible when pushing child views within a tab; never set hidesBottomBarWhenPushed = true or hide the tab bar programmatically during in-tab navigation.

Ios Voiceover Labels

Every interactive element must have a descriptive .accessibilityLabel that communicates its purpose; icon-only buttons with no visible text are the most common failure case.

Ios Voiceover Order

Ensure VoiceOver reads elements in a logical, content-meaningful order; use .accessibilitySortPriority() to override layout-driven order when the visual position produces a nonsensical traversal sequence.

Keyboard Tab Order

Every interactive element must be reachable via Tab key in a sequence that matches the visual reading order — left-to-right, top-to-bottom — so keyboard-only users can navigate without disorientation (WCAG SC 2.4.…

Kpi Card Secondary Variation

When rendering a 2×2 KPI grid, vary the secondary element in each card. Choose from the variation toolkit: trend % + arrow, mini progress bar (h-2), comparison text ('vs 380 last week'), sparkline (inline h-8 chart), sta…

Landmark Elements

Major page regions MUST be wrapped in HTML landmark elements — <header>, <nav>, <main>, <aside>, <footer>, <section aria-labelledby>, <form aria-label> — so screen reader users can jump directly to any region.

Light Mode Default Fallback

Light mode must be the default color scheme defined in :root; dark mode is an override layer applied via [data-theme='dark'] or @media (prefers-color-scheme: dark) — never the base layer.

Loading State Feedback

The UI must acknowledge every user-initiated action within 100ms — either by showing the completed result immediately (optimistic update) or by entering a visible loading state that persists until completion.

Navigation Flat When Shallow

When a product or section has ≤ 7 primary destinations, use flat top-level navigation (all items visible at once in a horizontal nav bar, tab bar, or sidebar list) rather than grouping them behind nested menus or accordi…

No Aria Patching Native

Never add ARIA roles to non-semantic elements when a native HTML element already provides the same semantics — use the native element instead.

No Casual Nav Sections

A new root-level navigation section must not be added unless it is confirmed that the content cannot fit inside an existing section — IA growth must be by deepening before broadening.

No Divergent Platform Flows

Entirely different task flows for the same user goal on different platforms are prohibited unless the platform constraints that necessitate the divergence are explicitly documented and justified.

No Fixed Widths Narrow

Fixed pixel widths that cause horizontal overflow or layout breakage on viewports narrower than 375px are forbidden — use fluid widths, max-width, or container queries instead.

No Heavy Shadows Per Component

Components must not define their own novel box-shadow values — all shadow styles must come from the design token system's elevation scale.

No Hidden Focus Outline

Focus outlines must not be removed unless an equivalent visible focus indicator with at least 3:1 contrast ratio replaces them — outline:none without a replacement is forbidden.

No Justified Text Narrow

CSS `text-align: justify` is BANNED on any text container narrower than 45ch or on any mobile viewport without CSS hyphenation enabled (`hyphens: auto`); it produces uneven word-spacing rivers that destroy reading rhythm…

No Keyboard Trap

Users must always be able to move keyboard focus out of any component using standard keys (Tab, Shift+Tab, or Escape); trapping focus in a non-modal context makes the interface completely unusable for keyboard-only and a…

No Mixed Visual Languages

Corner radii, shadow styles, and type scales must be visually consistent within any single user flow — mixing divergent visual language systems (e.g.…

No New Visual Primitives

New colors, fonts, or icon families not grounded in the existing token system must not be introduced without explicit token extension — raw visual primitive values outside the token layer are forbidden.

No Pointer Only Components

Custom interactive components must be fully operable by keyboard alone, not only by mouse or touch — any component that requires a pointer device to activate or dismiss is non-compliant.

No Shipping A11y Violations

Features that pass functional tests but contain known accessibility violations must not be shipped — a11y compliance is part of the definition of done, not a post-ship enhancement.

No Silent A11y Sacrifice

Accessibility and clarity must not be silently dropped when they conflict with speed or visual aesthetics — any deliberate accessibility trade-off must be explicitly documented with a plan.

No State Reset Without Confirm

Navigation away, session timeout, or flow reset must not silently discard unsaved changes or mid-flow state — users must be prompted to confirm or offered to save before loss occurs.

No Terminology Drift

A concept must be named identically throughout a single user flow — switching between synonyms or related terms mid-flow (e.g., 'Workspace' → 'Project' → 'Team') is forbidden.

No Undocumented Platform Concept Rename

Core feature and concept names must not differ between platforms unless the renaming decision is explicitly documented and justified in a design decision record.

No Uniform Spacing Without Headings

Unrelated content blocks must not use identical spacing between them when no heading or visual separator distinguishes their boundaries — spacing variation is itself a structural signal, and uniform spacing creates an un…

No Uniform Spacing Without Variation

Do not apply uniform 8pt grid spacing mechanically to every element without variation. The 8pt grid is a floor — not a ceiling.…

Noun Based Nav Labels

Navigation labels must be noun-based, consistent, present-tense, and free of jargon, marketing language, or cleverness — users navigate to destinations, not actions.

Number Unit Ratio

When displaying a metric with a unit (K, M, %, GB, /mo, $, etc.), render the number at 2× the unit's font size.

Opentype Features On

By default, browsers activate only a small subset of OpenType features; production CSS MUST explicitly enable `kern` (kerning), `liga` (standard ligatures), and numeric figure features (`tnum`/`lnum`) at minimum — and SH…

Page Section Density

Page sections must use density-appropriate spacing: primary marketing sections use generous padding (py-20 sm:py-32 / 80px–128px); application content areas use moderate density (py-8 / 32px); dense data tables and dashb…

Page Transition Out In Timing

Page transitions must use asymmetric timing: exit in 150-200ms (ease-in, accelerating out of view) and entrance in 250-400ms (ease-out, decelerating into position) — exits must complete before entrance begins in route-ba…

Permissions Human Readable

Permission and role labels in UI must describe what the user can do in plain language, not surface technical flag names, database identifiers, or internal role codes.

Pill Toggle No Dropdowns In Cards

Inside a data card:

Plain Language

Product copy must use everyday language rather than technical or domain-specific jargon — if a 10-year-old would need to look it up, rephrase it.

Platform Interaction Conventions

Each platform's native interaction conventions — gestures on iOS/Android, keyboard shortcuts on desktop, pointer interactions on web — must be supported rather than overridden by custom implementations.

Platform Native Navigation

Navigation structure and affordances must conform to the established conventions of each target platform — iOS uses tab bar + navigation stack, Android uses bottom navigation + back stack, web uses top nav + breadcrumbs.

Popover Vs Tooltip

Use a tooltip (role=tooltip, hover+focus triggered, short text only) for supplementary labels ≤ 1 line with no interactive content.…

Popstate Back Forward

Single-page applications must listen to the popstate event and restore the correct view state when the user navigates back or forward with browser controls.

Prefers Contrast

Designs must respond to prefers-contrast:more by increasing text and border contrast, and must use CSS system color keywords when prefers-contrast:forced is active to support Windows High Contrast Mode.

Preserve User Input On Error

When a form fails validation or a submission error occurs, all user-entered data must be retained in the fields so users can correct only the erroneous inputs without re-entering everything.

Primary Content First

The primary task or content must appear first in DOM order and receive the highest visual prominence — supplementary content, sidebars, and ads must come after the main content both structurally and visually.

Prioritize Critical Errors First

When a form submission produces multiple validation errors: (1) rank errors by severity (blocker > warning > suggestion); (2) display the highest-severity error prominently at the top of the form, adjacent to the offendi…

Progress Feedback Long Operations

Any operation that takes ≥300ms from user action to completion must display a visible loading indicator adjacent to the affected UI element.…

Propose Starter Tokens

If a project contains no design/tokens/* files (or equivalent CSS custom property / Tailwind token definitions): create minimal starter token files covering color (brand, surface, text), typography (font families, scale,…

Pwa Web App Manifest

A PWA manifest requires ALL of the following or the install prompt will not appear:

Reading Order Matches Visual Order

The sequence in which elements appear in the HTML source must match the sequence in which they appear visually on screen. If CSS is disabled, the page must remain comprehensible in the same logical order.…

Refactoring Ui Hierarchy

Not everything deserves emphasis. Build hierarchy with at least 2–3 combined dimensions (size + weight + color + spacing). Labels must weigh less than values.…

Refine Not Add On Second Pass

On any iterative refinement pass: (1) tighten alignment, spacing, and visual rhythm of existing elements; (2) improve color consistency and weight hierarchy within existing components; (3) fix optical misalignments; (4) …

Required Field Indication

For every form with required fields:

Rtl Directional Icons Flip

When dir="rtl" is applied to the document or a container:

Save Form Progress

Long or high-stakes forms (multi-step wizards, job applications, checkout with many fields) should auto-save draft progress to localStorage or a backend draft endpoint so users can resume after accidental navigation, ses…

Screen Reader Friendly Copy

When writing any user-facing text in a UI:

Semantic Html For Interactive Elements

Match element to purpose:

Semantic Structure Over Visual Positioning

Structure must be programmatically determinable, not only visually implied:

Single Accent Color

A product's UI must use exactly one accent/tint color for all interactive affordances — buttons, links, toggles, active states, progress indicators, and focus rings — creating a consistent visual signal for interactivity…

Single Primary Action Per Component

Every interactive component must expose exactly one primary action; all other actions must use visually subordinate treatment (secondary, ghost, or icon-only styles).

Single Primary Action Per Screen

Each screen, dialog, or distinct user context must have at most one primary call-to-action; all other actions must be styled as secondary or tertiary.

Small Focused Experiment

Each A/B test or design experiment must change exactly one variable (or a tightly coupled cluster of related changes) — never bundle unrelated changes into a single experiment.

Smooth Scroll Css

Always set scroll-behavior: smooth on the html element for anchor navigation, paired with @media (prefers-reduced-motion: reduce) { html { scroll-behavior: auto } } — this is the complete CSS-native smooth scroll solutio…

Success Confirmation Visual Change

After any create, update, delete, or submit action completes successfully, confirm what changed with explicit language and a corresponding visible UI update — a toast alone is insufficient if the affected element is in v…

Success Message Next Step

Every success or confirmation message must state what action completed AND offer a clear next step or navigation option — never just 'Done' or 'Success'.

Suspicious Activity Next Step

Alerts for unusual sign-ins, unrecognized devices, or potential account compromise must name the specific event and provide a single primary CTA pointing to a guided remediation flow — never a generic 'suspicious activit…

Touch Action Css

Use the CSS touch-action property to explicitly declare which browser-native touch gestures are permitted on interactive elements — never rely on browser defaults when building custom scroll containers, carousels, or can…

Trust Signal Critical

Never fabricate social proof numbers, and never place trust badges on every section. These are the two highest-severity mistakes in trust signal design.

Trust Signal Placement

Place each trust signal at the moment it addresses a specific conversion objection — not wherever it fits visually. Each trust component type appears once, in one position.

Typography Letter Spacing

Letter-spacing MUST follow size-dependent rules: display text (36px+) uses -0.02em to -0.…

Upfront Field Requirements

Mandatory fields, format requirements, and character limits must be visible before the user attempts to submit — never revealed only after a validation error.

Uppercase Labels Tracking

Every label that identifies a data category, section heading in a card, or column header in a stat grid uses this exact recipe:

Url Reflects State

Every meaningful view, filter, or sort state in a web application must update the URL via the History API — any state a user can share or return to must be encoded in the URL.

User Value Metrics

UX experiment success metrics must reflect actual user value and behavior — task completion, error rate, retention, or outcome measures — not what is easiest to instrument (clicks, page views, session duration).

Ux Flow Task Completion

Before shipping any user-facing feature, walk through each primary task as a first-time user and confirm there are no confusion points, dead ends, or missing affordances — a flow that passes functional tests but leaves u…

Vary Aesthetic Per Generation

Each generated UI must vary its theme, fonts, and aesthetic — never reuse the same choices generation after generation. NEVER converge on common choices (e.g. always Space Grotesk) across distinct UI generation requests.

Verb Based Cta Labels

Label every button and action link with a specific verb phrase that describes the action it performs — never use generic labels like 'Submit', 'OK', 'Yes', or 'Confirm'.

Viewport Meta Required

Every web page must include <meta name='viewport' content='width=device-width, initial-scale=1'> and must never set maximum-scale or user-scalable=no.

Visual Design Safe Rules

Apply these 12 mathematically-verifiable visual design rules: (1) near-black not pure black (oklch 12–15% lightness); (2) near-white not pure white (oklch 96–98%); (3) saturate neutrals with brand hue at chroma < 0.…

Wcag Aa Default Target

All frontend components must meet WCAG 2.1 Level AA conformance by default — AA is the widely accepted legal and ethical baseline for web accessibility.

Web Safe Fallback Stack

Every `font-family` declaration for a custom web font MUST include a web-safe generic fallback stack ending in `serif`, `sans-serif`, or `monospace` — and SHOULD include at least one OS-native font (system-ui, -apple-sys…

Whisper Shadows

Shadow scale for light-mode card surfaces:

Will Change Sparingly

Apply CSS will-change only to specific elements that will animate imminently; never apply it to body, large containers, or elements that won't animate; remove or reset it after animation completes.

Z Index Stacking System

All z-index values must be drawn from a named token scale (base: 0, raised: 10, dropdown: 100, sticky: 200, overlay-backdrop: 300, overlay: 400, toast/notification: 500, tooltip: 600) — never hard-coded arbitrary integer…

Scope Public Facing Marketing

Defines the applicability scope for atoms aimed at public landing pages, marketing sites, blog/docs, and pre-auth surfaces.…

Template Animated Mesh Background

Pure-CSS animated mesh gradient background using @property custom properties for <percentage> interpolation and four radial-gradient layers drifting on a 12s ease-in-out infinite alternate cycle — zero JS, zero canvas.

Template Color Layer Application

@community/template-color-layer-application

Template Color Layer Primitive

@community/template-color-layer-primitive

Template Color Layer Semantic

@community/template-color-layer-semantic

Template Css Scroll Driven Animations

CSS scroll-driven animations using animation-timeline: scroll() and view() with animation-range — zero-JS reading-progress bar (scaleX on compositor) and viewport-entry reveal, with @supports fallback for Firefox.

Template Framer Motion Pattern

Motion.dev (formerly Framer Motion) core patterns: AnimatePresence exit animation, layout layoutId shared-element, whileHover/whileTap micro-interactions, and useReducedMotion hook — React-declarative animation for compo…

Template Gsap Scroll Trigger

GSAP ScrollTrigger pattern for scroll-linked section reveals, pinned scrub timelines, and snap — with gsap.matchMedia() prefers-reduced-motion guard and useGSAP hook for React/Next.js.

Template Gsap Stagger

GSAP stagger pattern using gsap.from with stagger: { each: 0.07, from: 'start' } and ease: 'power3.out' — grid-aware stagger, SplitText character stagger, and prefers-reduced-motion guard via gsap.matchMedia().

Template Intentional Gradient Hero

@community/template-intentional-gradient-hero

Template Lenis Smooth Scroll

Lenis v1.3.21 smooth scroll minimum-safe integration: skip on prefers-reduced-motion and touch devices (hover:none), syncTouch:false, duration:1.…

Template Liveblocks Selection Presence

Multiplayer form field presence overlay using Liveblocks: an absolutely-positioned halo border and name pill that appears around an input when another user has focused it, driven by Liveblocks `useOthers()` and `updateMy…

Template Motion System Tokens

Complete motion system token set as CSS custom properties: 5 duration tiers (80ms–600ms), 6 easing curves (cubic-bezier values for each intent), and 3 semantic spring configs — all collapsed to 0ms under prefers-reduced-…

Template Nested Corner Radius

@community/template-nested-corner-radius

Template Scroll Driven Progress Bar

Reading-progress bar using CSS animation-timeline: scroll(root) with scaleX transform (compositor-only, zero paint cost) — includes @supports fallback for Firefox and prefers-reduced-motion hide.

Template Shadcn Pricing Toggle

Monthly/yearly billing toggle from shadboard full-kit: a single discountRate state (0 = monthly, 0.…

Template Svg Chart Aria

Accessibility code template for SVG-based charts. Provides two patterns: (1) simple svg with role='img' and descriptive aria-label, (2) figure+figcaption+sr-only paragraph wrapping an aria-hidden SVG.…

Template Svg Draw On Stroke

SVG draw-on stroke animation using the pathLength='1' normalization technique — eliminates getTotalLength() JS calls by normalizing path length to 1, enabling pure CSS stroke-dashoffset animation.…

Template View Transitions Api

View Transitions API pattern using document.startViewTransition() for SPA route changes — cross-fade default, directional slide override at 350ms cubic-bezier(0.4,0,0.…

Template Web Animations Api

Web Animations API (element.animate()) pattern for imperative JS-driven animations with full playback control — .cancel(), .pause(), await .finished — at cubic-bezier(0.16,1,0.…

Template Webgl Shader Ogl

Minimum-viable animated WebGL noise/mesh-gradient shader background using OGL v1.0.…

Visual Philosophy

A visual philosophy is a named aesthetic movement (1-2 words) with a manifesto articulating how it expresses itself through space, form, color, scale, and composition — not a layout template, style guide, or design brief…

Metric Cls Cumulative Layout Shift

CLS is one of Google's three Core Web Vitals (alongside LCP and INP). It measures the visual stability of a page by summing the impact-fraction × distance-fraction of every unexpected layout shift during the page's lifet…

Metric Lcp Largest Contentful Paint

LCP is one of Google's three Core Web Vitals — it measures the render time of the largest image, video poster, or text block visible within the viewport during initial page load.…

Provocation No Frameworks

@community/provocation-no-frameworks

Button Type Explicit

Every `<button>` element MUST declare an explicit `type` attribute (`button`, `submit`, or `reset`). The HTML default is `submit`, which inside a `<form>` causes any unrelated button (e.g.…

frontend-engineering ↗ 9 · q4.0

Mobile First

CSS responsive breakpoints MUST be authored mobile-first: base styles target the smallest viewport, and `@media (min-width: ...)` queries layer on enhancements for larger viewports.…

frontend-engineering ↗ 3 · q4.0

Scope Frontend Review

Defines the preconditions and environmental requirements for running frontend design review and accessibility audit methods.…

frontend-engineering ↗ 6 · q4.0

Scope Mobile Native

Defines applicability for atoms whose guidance applies only to native mobile apps — iOS (Swift, SwiftUI, UIKit) and Android (Kotlin, Jetpack Compose, View system).…

frontend-engineering ↗ 3 · q4.0

Scope Server Side Only

Defines the applicability scope for atoms whose guidance applies only to server-side rendering, server components, API routes, edge functions, or backend code paths.…

Step Debounce Async Validation

@community/step-debounce-async-validation

Step Debounce Search Input

@community/step-debounce-search-input

frontend-engineering ↗ 6 · q4.0

Step Validate Required Fields

@community/step-validate-required-fields

Taxonomy Form Input Types

A taxonomy of HTML form input controls and their semantic types. The HTML5 specification defines 22 input `type` values plus several distinct elements (textarea, select, button).…

Z Index Stacking Context

A stacking context is a three-dimensional conceptualization of HTML elements along an imaginary z-axis perpendicular to the viewport.…

Server Vs Client Rendering

Choosing where rendering happens shapes performance, SEO, complexity, and developer experience. SSR streams HTML on every request, SSG pre-renders at build time, and CSR ships a JS bundle that hydrates a shell.…

frontend-engineering ↗ 3 · q4.0

Typescript Strictness

Enabling TypeScript's `strict: true` (which turns on strictNullChecks, noImplicitAny, strictFunctionTypes, and others) catches a large class of bugs at compile time — but on a legacy JS-to-TS codebase, the upfront migrat…

Type Html Artifact

Schema for an HTML artifact as consumed by design review and accessibility audit methods. Represents a parsed HTML document with extracted component metadata.

frontend-engineering ↗ 2 · q4.0

Voice Precise Technical

The voice used when writing technical specifications, code comments, and implementation guidance. Values exactness over brevity, uses precise CSS/HTML/ARIA terminology, and always provides working code examples.

Accessible Frontend

A comprehensive skill for reviewing any frontend artifact for accessibility compliance (WCAG 2.2 AA) and design quality (Nielsen heuristics).…

general ↗ 18 · q4.0

Accessible Modal

A complete bundle of atoms required to ship an accessible modal dialog. A modal is the most-failed accessible widget in production frontends — it requires focus management, keyboard handling, ARIA semantics, scroll conta…

general ↗ 16 · q4.0

Fintech Compliance Ui

A bundle of atoms for building financial-product UI surfaces that meet regulatory and trust expectations: number display formatting, secure input handling, audit-trail visibility, and clear status communication.…

general ↗ 21 · q4.0

I18n Ready Component

Atoms required to ship a component that works correctly in all locales — LTR + RTL, single + plural, English + CJK + Arabic.…

general ↗ 16 · q4.0

Performance Budget

Atoms required to set up and enforce a Core Web Vitals performance budget across CI and production. Combines synthetic Lighthouse gates, RUM telemetry via web-vitals.…

general ↗ 14 · q4.0

Rest Api Discipline

Atoms required to design, ship, and evolve a REST API that survives migration, scales beyond 10K rows per collection, and stays compatible with API gateways, SDK generators, and CDN caches.…

general ↗ 14 · q4.0

8pt Grid System

Aligning all spacing values to multiples of 8 px (with 4 px as the half-step) yields cross-device pixel-grid alignment for the major device pixel densities (1×, 1.…

Aesthetic Usability Effect

In a landmark ATM usability study, Kurosu and Kashimura found that perceived ease of use correlated more strongly with aesthetic rating than with actual operational ease.…

Animation Distraction Cost

Peripheral / off-axis animation playing while a user is reading prose reduces reading speed by roughly 38% and lowers comprehension scores, because the human visual system's motion-detection pathway involuntarily command…

Anthropic Brand Palette

Anthropic's official brand palette is: two neutral anchors (Dark #141413, Light #faf9f5), two grays (Mid Gray #b0aea5, Light Gray #e8e6dc), and three accents (Orange #d97757, Blue #6a9bcc, Green #788c5d).…

Atomic Design Method

A UI component system can be modelled as five compositional levels: Atoms (irreducible HTML elements like input, label, button), Molecules (small functional groups like a labeled input), Organisms (composite regions like…

Card Sort Method

Card sorting is a participatory IA research method in which 15–30 participants group labelled content cards into categories — open card sorts (participants name the categories) reveal mental models for greenfield IA, whi…

general ↗ 2 · q4.0

Color Blindness Types

Roughly 8% of men of Northern European descent and 0.5% of women have a color vision deficiency — broken into protanopia / protanomaly (red-perception, ~1% men), deuteranopia / deuteranomaly (green-perception, ~6% men, t…

Color Token Semantic Naming

Color tokens consumed by components should be named for their role (--primary, --accent, --bg, --text), not their hue (--blue-500, --green-700) — semantic naming insulates components from brand changes and lets a single …

Contrast Amplification

Text rendered light-on-dark (negative polarity) requires roughly 10% higher luminance contrast and one weight step heavier than the same text dark-on-light to achieve perceptual parity, because of halation: bright glyphs…

Contrast Ratio Aa Vs Aaa

WCAG 2.2 SC 1.4.3 requires luminance contrast ≥ 4.5:1 for normal text (Level AA) and SC 1.4.…

general ↗ 5 · q4.0

Density Vs Comfort Tradeoff

Higher information density (smaller type, tighter line-height, reduced whitespace) is appropriate for expert / pragmatist personas who scan and act, while lower density (larger type, generous line-height, more whitespace…

Design Token Cascade

Design tokens cascade through three tiers — primitives (e.g., --blue-500: oklch(62% 0.…

Doherty Threshold

Walter Doherty and Ahrvind Thadani at IBM found that when a computer system responds within 400 ms, users remain engaged in a tight cognitive loop — thinking and acting nearly continuously.…

Duration Perception Thresholds

Three response-time thresholds govern UI motion / latency perception (Card / Robertson / Mackinlay 1991, Nielsen 1993): 100 ms is the limit for perception of instantaneous response, 1 second is the limit for the user's f…

Easing Cubic Bezier

UI motion should use asymmetric cubic-bezier easings that decelerate at the end (e.g., cubic-bezier(0.4, 0, 0.2, 1) — Material's standard ease, or cubic-bezier(0.16, 1, 0.…

Easing Mood Mapping

UI motion 的 easing 选择不只是性能或物理学问题——每条曲线传达一种情绪：linear 用于无终点循环（spinner / shimmer），其他场景用 linear 等于宣告'这是程序的，不是产品的'；ease-out 系列（包括 cubic-bezier(0.16,1,0.…

Error Recovery Types

Error feedback should be placed at one of three levels matched to scope and severity: (1) inline next to the field / control that produced the error (form validation, individual save failure), (2) toast / banner for tran…

Fitts Law

The time to acquire a target with a pointer is approximately MT = a + b · log2(D/W + 1), where D is the distance to the target and W is the target's width along the movement axis — bigger targets at shorter distances are…

Gestalt Closure

When presented with a set of incomplete visual elements, the brain fills in the missing information to perceive a complete, familiar shape or boundary.…

Gestalt Common Fate

When multiple elements undergo the same motion — same direction, same speed, same timing — the brain groups them as belonging together.…

general ↗ 5 · q4.0

Gestalt Continuity

The visual system naturally follows paths of least curvature — a smooth line is perceived as continuing beyond interruptions, and elements arranged along a curve or line are grouped together as a sequence.…

Gestalt Figure Ground

The brain automatically segregates any visual scene into a figure — the object of attention, which appears closer, more defined, and more 'thing-like' — and a ground — the background, which appears further away and shape…

Gestalt Proximity

Visual elements positioned close to each other are perceived as belonging to the same group, regardless of their other visual properties.…

general ↗ 2 · q4.0

Gestalt Similarity

The brain groups visual elements that share one or more physical attributes (color, shape, size, orientation, texture).…

Goal Gradient Effect

Clark Hull first observed in rats that running speed increased as animals neared a food reward; subsequent human research confirmed the same pattern — effort, engagement, and speed all increase as people approach the com…

Hick Law

Decision time scales as approximately T = b · log2(n+1) where n is the number of equally probable, equally salient options — meaning each doubling of choices adds a constant unit of decision time, not a linear amount.

Hover Feedback Latency

Hover / focus / tap 等指针交互的视觉状态变化（颜色、阴影、scale、outline）必须在 100ms 之内开始播放，且总时长应在 100-200ms 内完成主要变化。这源于 Card-Robertson-Mackinlay 1991 的'感知瞬时'阈值——人脑对 100ms 内的反馈感知为'即时响应'。超过此值用户会启动'判断流程'：'我点中了吗？'或'按钮坏了？'，导致重复点击 / 焦虑 / 弃用。> 200m…

Hue Temperature Bias

Warm hues in the OKLCH 0°–60° and 300°–360° ranges (reds, oranges, magentas) tend to read as urgent / energetic / alarming and are widely used for warnings and CTAs, while cool hues in the 180°–240° range (cyans, blues, …

Idle Vs Error Vs Empty

Three states that all show 'nothing here' must be visually and semantically distinct: (1) idle / first-run — no query / filter / action yet, copy invites onboarding action; (2) empty result — query / filter ran successfu…

general ↗ 2 · q4.0

Jakob Law

Users transfer expectations from other sites to yours — a search bar in the top-right, a logo in the top-left that links home, a hamburger icon meaning menu, a shopping cart icon meaning cart — so deviating from web-wide…

Light Vs Dark Default

Long-form reading apps (Readwise, Instapaper, Medium, NYT) default to light themes because positive contrast (dark text on light background) yields ~2% faster reading speeds and lower error rates for sustained prose, whi…

Line Height Readability

Optimal line-height for body prose is in the 1.5–1.7 range (unitless multiplier of font-size), with editorial / long-form content tending toward 1.6–1.7 and dense UI body text tending toward 1.4–1.5; values below 1.…

Loading Skeleton Vs Spinner

Skeleton loaders produce shorter perceived wait times than spinners for content-shaped surfaces (lists, cards, articles) because they communicate what is loading, preserve final layout dimensions to avoid layout shift, a…

Miller Rule 7

Human short-term working memory holds approximately 7 ± 2 chunks of information (Miller 1956), with more recent psychometric work converging on a stricter limit of about 4 chunks (Cowan 2001) — a 'chunk' being any unit t…

Monospace Purpose

Monospace typefaces (JetBrains Mono, Berkeley Mono, IBM Plex Mono, Söhne Mono) are designed for code, log output, terminals, IDs / hashes, and tabular numerics where column alignment is semantically meaningful — using th…

Motion As Feedback

Animation in production UI must communicate one of: (a) cause-and-effect (clicking here triggered that), (b) origin / continuity (this panel came from that button), (c) state change (saved, loading, errored), or (d) spat…

Motion Hierarchy

在任意一个时刻，UI 中应该最多只有 1-2 个动效在表达'主要状态变化'（即视觉焦点位置）；其余元素的动效应被压缩到极短（< 150ms）或被禁用，否则用户的注意力被多个并行运动撕扯，每个动效的信息量都被稀释为零。这是 motion 设计的'信噪比'原则。

Occams Razor

William of Ockham's principle — 'entities should not be multiplied beyond necessity' — was formalised as a rule of parsimony in science and later adopted in design.…

Oklch Perceptual Uniform

OKLCH (Björn Ottosson, 2020) is perceptually uniform — a 5-point lightness step in OKLCH looks like the same brightness change regardless of hue, while the equivalent step in HSL produces a much larger change in yellows …

Optical Sizing

Type set at large display sizes (> ~36 px) wants tighter letter-spacing (-1% to -3%) and may carry higher stroke contrast, while type set at small body sizes (≤ ~14 px) wants looser letter-spacing (+1% to +3%) and lower …

Optimistic Update Tradeoff

Optimistic updates exchange immediate perceived responsiveness for two costs: (1) implementation complexity for rollback / reconciliation when the server rejects the operation, and (2) erosion of user trust when a previo…

Paradox Of Choice

Barry Schwartz synthesised psychological research showing that while some choice is essential for autonomy and satisfaction, an abundance of options triggers choice overload: users take longer to decide, feel less confid…

Pareto Principle

Vilfredo Pareto observed that 80% of Italy's land was owned by 20% of the population; Joseph M. Juran generalised this to quality management and product design.…

Peak End Rule

Psychological research shows that retrospective evaluations of an experience are dominated by two moments: the most intense emotional point (positive or negative) and how the experience ended.…

Postel Law

Jon Postel formulated this principle for TCP/IP implementations: a well-behaved system should accept a wide variety of valid and near-valid inputs without breaking, while always emitting strictly well-formed output.…

Reduced Motion Priority

Between approximately 5% and 30% of users have prefers-reduced-motion: reduce enabled — driven by vestibular disorders, migraine, motion-induced nausea, epilepsy risk, deliberate battery / focus preference, and OS defaul…

Spacing Token Progression

Effective spacing scales follow a near-geometric progression (e.g., 4, 8, 12, 16, 24, 32, 48, 64, 96, 128) rather than a linear one (4, 8, 12, 16, 20, 24, …) — equal *ratios* between steps produce visually balanced size …

Stagger Feel Organic

Stagger（错位入场）的相邻 delay 应在 50-100ms 之间，最佳点在 70-80ms。这个区间利用了人类视觉系统的时间合成阈值——大脑把 < 80ms 的相继事件融合为'连续运动'，而 100-150ms 之间被感知为'有先后但相关'。低于 30ms 的延迟在视觉上等同于同时发生（stagger 退化为齐响），高于 150ms 则每个元素被解读为独立动画事件，整体节奏感丢失。

Tesler Law

Larry Tesler observed that all non-trivial applications contain inherent complexity that exists in the domain itself, not merely in the interface.…

Tonal Palette 12 Step

The Radix Colors 12-step scale architecture establishes that: steps 1–2 serve as page/subtle backgrounds at L=0.97–0.99 light (L=0.10–0.…

Type Scale Modular

A modular type scale multiplies a base font-size by a fixed ratio (typically between 1.125 and 1.618) to derive each step — common ratios are Minor Third (1.2), Major Third (1.25), Perfect Fourth (1.…

Zeigarnik Effect

Bluma Zeigarnik, building on Kurt Lewin's tension-system theory, found that incomplete tasks create a persistent cognitive tension that keeps them more accessible in memory than finished tasks.…

Tool Lighthouse

Google Lighthouse is an automated auditing tool for web pages that measures performance, accessibility, best practices, SEO, and PWA metrics.…

Voice Customer Support

The voice used in help articles, support replies, and onboarding emails. Calm, empathetic, step-by-step. Acknowledges the user's situation before solving it.…

help-center ↗ 5 · q4.0

Flag As Language

Using a national flag icon to represent a language in a language switcher. Flags signify nation-states, not languages — the mapping from flag to language is many-to-many, often contested, and can offend or confuse users …

Bidi Direction

The Unicode Bidirectional Algorithm (UAX #9) defines how mixed-direction text is laid out: paragraph-level direction (set by `dir='rtl'` or auto-detection from first strong character) plus per-character direction inheren…

i18n ↗ 6 · q4.0

Feedback I18n Launch V1

Accumulated execution feedback for first-release i18n rollouts using @community/collection-i18n-ready-component.…

Icu Message Format

ICU MessageFormat is the industry-standard syntax for parameterized translatable strings.…

No String Concat

Every user-facing string must be a single, complete sentence template owned by the translation pipeline.…

i18n ↗ 6 · q4.0

Cjk Line Break

Containers that may render CJK text MUST set `lang` correctly on the HTML element (lang='ja', 'zh-Hans', 'zh-Hant', 'ko') and use `line-break: strict` (or `normal` with explicit `word-break: keep-all` where words must no…

Scope Localized Product

Defines applicability for atoms whose guidance applies only to product surfaces that ship to multiple locales (≥ 2 supported languages).…

Bcp 47

Best Current Practice 47, the IETF document collection (currently RFC 5646 + RFC 4647) defining the syntax and use of language tags.…

Transform Locale Fallback Chain

Computes the BCP 47 locale fallback chain for a requested locale tag. Implements RFC 4647 'Lookup' algorithm: try the most specific tag, then truncate subtags from the right, fall through to a default.…

Transform Relative Time Format

Formats a date as a localized relative time string ('5 minutes ago', 'in 2 days', 'last month') using the platform `Intl.RelativeTimeFormat` API.…

Type Locale Tag

Schema for a locale identifier conforming to BCP 47 (RFC 5646), the IETF standard for language tags. A locale tag combines language, optional script, optional region, and optional variants (e.g.…

i18n ↗ 6 · q4.0

Snowflake Server

A production server that has been hand-tweaked over its lifetime — packages installed manually, config files edited via SSH, cron jobs added by request, library versions pinned to fix a specific bug — to the point where …

Rfc 1918 Private Ranges

RFC 1918 (Y. Rekhter et al., February 1996) allocates three IPv4 prefixes for use in 'private internets' — networks that do not need globally-unique addresses and whose traffic does not transit the public internet.…

infrastructure ↗ 6 · q4.0

Blue Green Deploy

Run two identical production environments (blue and green); only one serves live traffic at a time.…

Immutable Infrastructure

An immutable artifact (image) is built once and produces identical instances every time. Configuration drift cannot accumulate because the system is never modified after boot.…

Iac Required

All infrastructure changes go through pull request → plan review → approved apply, executed by an automation account that the developer cannot bypass.…

Constraint Scroll Locked Modal Only

Body scroll lock (overflow:hidden / scroll-position pinning) is permitted only while a fully-blocking overlay (modal dialog, full-screen drawer, lightbox) is visible. It must be released the moment the overlay closes.

interaction ↗ 3 · q4.0

Check Content Width Constrained

Validates that main content containers constrain max-width to keep prose readable: ≤ 720px (~75ch) for prose, ≤ 1280px for general content.…

layout ↗ 2 · q4.0

Check Grid Baseline Aligned

Validates vertical rhythm by checking that block gaps, heading margins, and body line-height are integer multiples of a baseline grid (4px or 8px).…

layout ↗ 2 · q4.0

Check Mobile First

Validates mobile-first responsive authoring: viewport meta tag is correct, media queries layer up via min-width (not max-width), zoom is not disabled, and no fixed widths exceed 375px in default styles.

layout ↗ 2 · q4.0

Check Spacing Rhythm

Validates that margin/padding/gap values align to a 4px or 8px base grid (configurable). Off-grid values (e.g. 13px, 7px) break vertical rhythm and indicate ad-hoc spacing decisions.

layout ↗ 1 · q4.0

Dark Pattern Consent

UI patterns that nudge, manipulate, or coerce users into agreeing to data processing they would not freely choose — pre-checked boxes, asymmetric button prominence, multi-step opt-out journeys, dark-side defaults.…

Coppa 13 Yo Threshold

If your service is 'directed to children' OR you have actual knowledge that a specific user is under 13, COPPA applies. Required: clear privacy notice; verifiable parental consent (credit card $0.…

Right To Be Forgotten

An end-to-end deletion architecture that fulfills GDPR Article 17 'right to erasure' (and CCPA §1798.105 right to delete) within the legally-required window.…

Data Minimization

Every data field collected creates ongoing legal liability (breach notification, DSAR fulfillment, retention controls), engineering cost (encryption, access controls, audit), and ethical risk. Default to NOT collecting.…

legal-compliance ↗ 5 · q4.0

Cookie Consent Banner

The consent banner must (1) load with NO non-essential cookies set, (2) give equally-prominent 'Accept all' and 'Reject all' options at the top level (CNIL guidance, 2020), (3) describe the categories of cookies and name…

Voice Legal Formal

The voice used in Terms of Service, Privacy Policies, DPAs, and SOC2 reports. Precise, defined-term-heavy, emotion-free. Passive voice is permitted when the actor is irrelevant.…

loading-states ↗ 7 · q4.0

Template Skeleton Loader

Pure CSS skeleton screens with shimmer effect — no JS. Parameterized width/height via inline styles. Respects prefers-reduced-motion by halting animation.

longform-journalism ↗ 6 · q4.0

Voice Editorial Investigative

The voice used in investigative reporting and longform features. Sourced, specific, predominantly past tense, attribution-heavy, allergic to adjectives that smuggle in opinion.…

Leaky Target

A feature that is computed using information that would not have been available at inference time — typically because the feature pipeline reads the latest value of some column instead of the value as-of the prediction t…

Evaluation Set Frozen

Generalization guarantees rely on the test set being statistically independent of the modeling decisions.…

machine-learning ↗ 6 · q4.0

Feature Store

A centralized system that defines, computes, stores, serves, and versions features for ML models — providing a single source of truth so the same feature definition is used in offline training and online inference.

Train Serve Skew

Train-serve skew is the gap between the feature distribution a model saw during training and the distribution it sees in production.…

Model Card Required

A Model Card is a 1-3 page structured document, version-controlled alongside the model artifact, containing nine sections: (1) Model Details — name, version, date, owner, license, citation; (2) Intended Use — primary use…

marketing-landing ↗ 6 · q4.0

Voice Marketing Bold

The voice used on confident product landing pages and feature launches. Verb-first, short, declarative, kinetic. Sounds like Stripe, Linear, Vercel, Framer headlines — momentum over explanation.

Check Animation Duration

Validates animation/transition durations fall within tasteful UI ranges (100–200ms micro, 200–400ms state, 300–600ms entrance) and flags durations > 3s as potential vestibular hazards.…

motion ↗ 2 · q4.0

Example Framer Page Transition

Framer's marketing site uses a two-stage page transition: outgoing content fades down (opacity 1 → 0, translateY 0 → -8px) over 280ms, immediately followed by incoming content fading up (opacity 0 → 1, translateY 12px → …

motion ↗ 5 · q4.0

Example Linear Card Hover

Linear's issue cards in the backlog/board view lift ~1.5px on hover with a subtle border-color shift from #2C2D33 to #3A3B42 and a soft new bottom shadow.…

motion ↗ 4 · q4.0

Example Stripe Payment Success

After a successful payment, Stripe Checkout displays a 56px circle that draws itself in (~400ms), then a checkmark path strokes through (~300ms), then the words 'Payment successful' fade up (~200ms).…

motion ↗ 5 · q4.0

Example Vercel Hero Gradient

Vercel's homepage hero uses a mesh gradient (the 'Vercel beam') that drifts very slowly behind the headline — cyan #00DFD8 and magenta #FF0080 radial-gradient blobs at ~10% alpha, animating their position over a 16-20 se…

motion ↗ 4 · q4.0

Template Button Press

Tactile button press feedback — transform-scale + shadow pulse + color darken on :active. Asymmetric timing (fast in, slower out) sells the physicality. Works on touch and mouse equally.

motion ↗ 8 · q4.0

Template Card Hover Lift

Card / button hover lift with shadow deepening — the Linear / Vercel micro-interaction signature. Includes active-press snap-back, focus-visible parity for keyboard, and full reduced-motion fallback.…

motion ↗ 6 · q4.0

Template Easing Curves

Canonical easing + duration token set as CSS custom properties. Drop into :root and reference everywhere — eliminates the magic-number cubic-bezier copy-paste that plagues most codebases.…

motion ↗ 6 · q4.0

Template Fade Stagger

Children of a list / grid fade-up in sequence using nth-child animation-delay — pure CSS, no JS. Triggered by adding .is-revealed to the parent (combine with scroll-reveal observer for on-scroll cascades).

motion ↗ 7 · q4.0

Template Loading Spinner

SVG circle spinner with rotating arc — currentColor-aware, parameterized size, fully accessible (role=status + sr-only label). Single rotation animation, no JS, no GIF. Reduced-motion shows a static partial ring.

motion ↗ 8 · q4.0

Template Page Transition View Transitions

Smooth page transitions using the View Transitions API (Chrome 111+, Safari 18+). Single-page apps get cross-fade for free; shared elements (e.g.…

motion ↗ 6 · q4.0

Template Scroll Reveal Vanilla

Scroll-reveal animation using IntersectionObserver — no GSAP, no AOS, ~25 lines of JS. Adds .is-visible class once an element scrolls into view; does NOT re-trigger on scroll-out.…

motion ↗ 8 · q4.0

Template Spring Config

Spring physics animation helper using the Web Animations API — no Framer Motion, no React Spring, ~50 lines. Generates a keyframe sequence from spring physics and runs it via element.animate().…

motion ↗ 5 · q4.0

Template Dropdown Menu

Accessible dropdown menu with full keyboard navigation: ArrowDown opens + moves focus, ArrowUp/Down to traverse, Home/End edges, Esc closes, Enter activates.

navigation ↗ 5 · q4.0

Template Tabs Keyboard

WAI-ARIA Authoring Practices tabs: roving tabindex, ArrowLeft/Right (or Up/Down) traversal, Home/End to jump, optional auto-activation on focus, fully accessible.

navigation ↗ 7 · q4.0

notifications ↗ 11 · q4.0

Template Toast Stack

Toast notification stack with auto-dismiss, polite live region, slide-in animation, and stack management. Call window.toast(message, options) to push.

Alert On Everything

Configuring alerts for every metric threshold, every error log, every CPU spike — producing a constant stream of pages that on-call learns to ignore.…

Percentile Vs Mean

Real-world request latencies are not normally distributed — they are heavy-tailed mixtures of fast cache hits, slower DB reads, occasional cold starts, and rare timeout-driven retries.…

ops-observability ↗ 6 · q4.0

Error Budget Policy

A pre-agreed, written policy that describes what happens automatically when a service consumes its error budget faster than the SLO target allows — typically a feature-freeze, a focus on reliability work, or shifting on-…

Three Pillars Observability

Metrics tell you what is happening at scale (RED, USE, four-golden-signals); logs tell you what happened in a specific event (errors, audit, debug); traces tell you why a request was slow or failed across service boundar…

Slo Required For Prod

An SLO is the contract between the service team and its users about how reliable the service must be. The SLO has three required components: (1) an SLI — the precise mathematical definition of 'good' (e.g.…

Blocking Third Party

Loading third-party JavaScript (analytics, ads, tag managers, marketing pixels, A/B testing snippets) synchronously in the <head> blocks the parser, delays First Contentful Paint, and exposes the page's performance to th…

Check Image Optimization

Validates image optimization: modern formats (webp/avif), responsive srcset, lazy-loading for below-fold, intrinsic width/height for CLS prevention, and decoded-byte-size proportional to displayed dimensions.

performance ↗ 1 · q4.0

Rail Targets

Chrome's RAIL model (introduced 2015 by Paul Lewis & Paul Irish, reaffirmed in 2024 documentation) defines four perceptual budgets keyed to user activity: (1) RESPONSE — input acknowledgment within 100ms (Doherty thresho…

performance ↗ 7 · q4.0

Feedback Perf Budget Rollout

Accumulated execution feedback from teams adopting Core Web Vitals performance budgets via @community/collection-performance-budget.…

performance ↗ 5 · q4.0

Metric Inp Interaction To Next Paint

INP measures the latency from a discrete user input (click, tap, key press) to the next frame painted by the browser. Replaced FID (First Input Delay) as an official Core Web Vital in March 2024.…

performance ↗ 7 · q4.0

Image Lcp Priority

Hint the browser that the LCP image is the most important resource on the page. Combines `<link rel='preload' as='image'>` with `fetchpriority='high'`, modern format negotiation, and explicit dimensions to drive sub-2.…

Perceived Vs Actual

Hard upper bounds for perception (RAIL model + Doherty threshold): user input MUST acknowledge within 100ms (button press feedback, focus ring, ripple); animation frames MUST commit within 16.…

Cls Budget

Set a CLS budget of 0.1 (Lighthouse synthetic, mobile preset). Block PRs whose budget regression is >0.05 above main. Track field CLS via RUM (web-vitals.js + analytics endpoint) and alert on rolling-p75 ≥ 0.…

Image Optimization

Every raster image in an HTML artifact MUST: (a) declare `loading='lazy'` for below-the-fold images, (b) be served in a next-gen format (WebP or AVIF) with a fallback, and (c) provide a `srcset` / `<picture>` for respons…

performance ↗ 4 · q4.0

Inp

Interaction to Next Paint — a Core Web Vitals metric measuring the latency between a user input (click, tap, key press) and the next frame painted by the browser.…

Tool Web Vitals Js

Google's web-vitals.js library exposes the Core Web Vitals (LCP, INP, CLS) and supplemental metrics (FCP, TTFB) in a small, consistent API.…

Template Cmd Palette Shell

Cmd+K command palette shell: trigger combo, modal with input, filtered list, ArrowUp/Down + Enter navigation, Esc close. Plug your own command source into window.cmdPalette.setCommands().

power-user ↗ 11 · q4.0

Template Kbd Shortcut Overlay

Press '?' anywhere to reveal a grid of keyboard shortcuts. Esc closes. Modal overlay with focus trap and scroll lock.

power-user ↗ 6 · q4.0

product-engineering ↗ 5 · q4.0

Build Vs Buy

Whether to build an internal solution or pay for a managed service for non-core capabilities (auth, payments, search, email, analytics).…

Eval User Input

Passing user-controlled strings directly to dynamic code evaluators — JavaScript eval(), Function constructor, Python exec()/eval(), Ruby eval/instance_eval, PHP eval() — resulting in arbitrary code execution.

Md5 For Passwords

Using general-purpose cryptographic hash functions (MD5, SHA-1, SHA-256, SHA-512) to hash passwords — even with a salt — rather than password-specific slow hashing algorithms designed to resist GPU-accelerated cracking.

Open Redirect

Accepting a redirect destination URL from user-controlled query parameters (?next=, ?redirect=, ?return_to=, ?url=) without validating it against an allowlist of permitted destinations.

Sql String Concat

Building SQL queries by concatenating or interpolating user-controlled strings directly into query text — the classic SQL injection (SQLi) vulnerability, #1 on OWASP for over a decade.

Trusting Client Validation

Relying on browser-side validation (HTML5 required/pattern attributes, JavaScript form checks) as the security boundary, with no equivalent validation on the server — trivially bypassed with curl, Postman, or DevTools.

Check Content Security Policy

CSP header must be present on HTML responses, must not contain 'unsafe-inline' or 'unsafe-eval' in script-src, and must not use wildcard (*) as the sole source in script-src or default-src.

Check Cookie Secure Flags

Session and auth cookies must carry Secure, HttpOnly, and SameSite=Strict (or Lax for OAuth flows).…

Check Dependency Audit

All project dependencies must pass a vulnerability audit with zero high/critical severity findings. Checks must run in CI on every PR and on a scheduled daily basis against the production manifest.

Check Https Everywhere

Every HTTP response must include an HSTS header with max-age ≥ 31536000 (1 year), includeSubDomains, and preload. No http:// links must appear in HTML output.

Check No Credentials Client

Scans client-bundled JS and HTML for hardcoded API keys, secrets, JWTs, and credentials (OpenAI, Anthropic, AWS, GitHub, Stripe, Google), and detects sensitive env vars exposed via NEXT_PUBLIC_/VITE_/REACT_APP_ prefixes.

security ↗ 1 · q4.0

Check Secrets Not In Git

No secrets (API keys, passwords, tokens, private keys, connection strings) must exist in any git commit — past or present. A pre-commit hook and CI scan must enforce this automatically.

Csp Strict

A Content-Security-Policy header that allowlists ONLY the origins your app actually loads — blocks XSS by refusing inline scripts and unauthorized origins.

Defense In Depth

Security controls at every layer of the stack — network perimeter, transport, authentication, authorization, input validation, output encoding, and monitoring — so that compromise of any single layer does not result in f…

security ↗ 6 · q4.0

Input Validation Allowlist

Validate all user input against an explicit allowlist of permitted characters, formats, or enum values — reject everything that does not match, rather than attempting to strip or escape known-bad patterns.

Jwt Signed Not Encrypted

JSON Web Tokens signed with HS256 or RS256 provide tamper-evident claims, but the payload is base64-decoded plaintext — never place secrets or PII inside the JWT body.

Rate Limit Token Bucket

A token-bucket algorithm that allows short bursts while enforcing a sustained request rate — the standard rate-limiting primitive for APIs and login endpoints.

security ↗ 1 · q4.0

Owasp Auth Failures

Authentication systems must implement: account lockout or exponential backoff after failed attempts, multi-factor authentication for sensitive operations, secure session management (HTTPOnly + Secure cookies, short-lived…

Owasp Broken Access Control

Every server-side request must verify the requesting user is authorized for the specific resource and action — never trust client-side authorization signals, never assume that hiding a UI element also protects the underl…

Owasp Cryptographic Failures

Sensitive data must be encrypted in transit (TLS 1.2+) and at rest (AES-256 or ChaCha20-Poly1305). Passwords must use dedicated slow hash functions (bcrypt/Argon2id/scrypt).…

Owasp Data Integrity Failures

Deserialized data from untrusted sources must be validated against a strict schema before use. Software updates, packages, and CI/CD pipeline steps must verify cryptographic signatures.…

Owasp Injection

User-supplied input must never be concatenated into interpreter commands or queries.…

Owasp Insecure Design

Security requirements must be established before implementation begins, not retrofitted after.…

Owasp Logging Monitoring Failures

Applications must log authentication events (success and failure), authorization failures, input validation failures, and all high-value transactions with sufficient context (timestamp, user ID, IP, action, outcome).…

Owasp Security Misconfig

Every layer of the stack (cloud, network, platform, web server, application framework, database, VM, container) must be hardened with least-privilege defaults, unnecessary features disabled, and configuration drift detec…

Owasp Ssrf

Any server-side HTTP fetch using user-controlled URL input must validate the resolved destination against an explicit allowlist of domains or IP ranges. Block private IP ranges (RFC 1918: 10.0.0.0/8, 172.16.0.0/12, 192.…

Owasp Vulnerable Components

Every third-party dependency must be inventoried (SBOM), continuously scanned for known CVEs, and updated within 30 days for critical/high vulnerabilities.…

Csrf Token State Changing

Every state-changing HTTP request (POST, PUT, PATCH, DELETE) must include a CSRF token validated server-side.…

No Credentials Client

API keys, secrets, OAuth client secrets, database connection strings, private signing keys, and any other credentials MUST NEVER appear in client-shipped code (HTML, JS bundles, source maps, config JSON, environment vari…

Passwords Bcrypt Or Argon2

User passwords MUST be hashed with bcrypt (cost factor ≥ 12), Argon2id (memory ≥ 64 MiB, iterations ≥ 3, parallelism ≥ 1), or scrypt (N ≥ 2^17, r = 8, p = 1). Never store plain-text passwords.…

Secrets Never In Source

Secrets (API keys, database passwords, private keys, OAuth client secrets, service account credentials) must NEVER appear in source code, committed to version control, or embedded in build artifacts.…

Sql Prepared Statements

User-supplied values must NEVER be interpolated or concatenated into SQL query strings. All SQL queries with external input must use parameterized queries (prepared statements) with typed parameter binding.…

Tls Everywhere

All HTTP traffic must be served exclusively over TLS 1.2+. HTTP (port 80) must redirect to HTTPS (301) and the `Strict-Transport-Security` header must be set with `max-age ≥ 31536000` (1 year) and `includeSubDomains`.…

Template Empty State

Polite empty-state block: SVG illustration slot, heading, subtitle, primary CTA, secondary link. Centered layout, accessible heading hierarchy.

states ↗ 4 · q4.0

Test The Mock

Tests that mock every collaborator and then assert on the mock interactions (`expect(mock.send).toHaveBeenCalledWith(...)`) verify implementation details rather than behavior.…

Test Pyramid Ratios

Common observed test-suite distributions across mature codebases: (1) Mike Cohn's classical pyramid: 70% unit / 20% integration / 10% E2E, by test count. (2) Kent C.…

Snapshot Restraint

Snapshot tests are valuable for serialization formats, JSON schemas, and rare 'large output equivalence' cases — and dangerous when used as a default for component or unit testing.…

testing ↗ 5 · q4.0

Test Pyramid

Structure tests as a pyramid: 70% unit tests (pure functions, single class/component, no I/O — milliseconds each), 20% integration tests (multi-component or single-service against real DB/queue with test fixtures — secon…

Flaky Quarantine

Any test failure that does not reproduce when re-run with no code change is flaky.…

Tool Playwright

Microsoft's Playwright is a cross-browser automation framework for end-to-end testing.…

Template Dark Mode Toggle

One-shot dark mode toggle: CSS variables driven by data-theme attribute, prefers-color-scheme fallback, and localStorage persistence. No flash of wrong theme on reload.

theming ↗ 6 · q4.0

Template Oklch Dark Mode Cascade

Single-variable OKLCH cascade: change one --hue and the entire palette + dark mode follow. Auto-flips via prefers-color-scheme and supports manual data-theme override.

theming ↗ 4 · q4.0

Check Body Readability

Verifies body prose meets readability requirements: 16px+ font-size, 1.5–1.7 line-height, letter-spacing within ±0.025em, and font-weight 400–500. Based on Butterick + Bringhurst typographic conventions.

typography ↗ 1 · q4.0

Check Font Blacklist Applied

Detects blacklisted default font-families (Arial, Helvetica, Times New Roman, Comic Sans, Papyrus, Courier New) used as PRIMARY font, and detects sites that load no custom fonts at all (signaling lack of typographic care…

typography ↗ 1 · q4.0

Check Line Length Optimal

Measures rendered characters-per-line (CPL) for prose blocks and flags content that violates the 45–75 character optimal range (35–90 acceptable). Long lines harm readability; short lines fragment reading rhythm.

typography ↗ 1 · q4.0

Example Atlantic Longform

The Atlantic's longform article opens with a full-bleed cover image (16:9, ~80vh tall) overlaid with a 64px serif headline (their custom 'Atlantic Serif'), 24px deck below in italic, and byline.…

Example Nytmag Feature

NYT Magazine feature stories use bold expressive opening typography: the headline is 80-120px in 'NYT Cheltenham' or 'NYT Karnak' display serif, often laid over or beside the cover image with intentional overlap.…

Example Pitchfork Review

Pitchfork album reviews are dominated by the 'score' — a massive 96px+ numeric rating (e.g., '8.7') displayed prominently next to the album cover. The cover art is shown at ~480px square.…

Example Readwise Reader

Readwise Reader strips articles to a focused reading view with configurable typography (Newsreader, Charter, Inter), themes (sepia #F4ECD8, dark #1C1917, light #FFFFFF), and 600-720px column widths.…

Optimal Line Length

Optimal reading line length for body text is 45–75 characters per line (CPL) for single-column layouts, and 40–50 CPL for multi-column layouts. Lines outside this range measurably reduce reading speed and comprehension.

typography ↗ 2 · q4.0

Body Readability

Body text MUST meet the minimum readability floor: `font-size` ≥ 16px (1rem) and `line-height` ≥ 1.5 (unitless). Text below 16px causes user-pinch-zoom on mobile; line-height under 1.…

typography ↗ 9 · q4.0

Content Width Constrained

Long-form content containers (article, blog post, documentation, prose) MUST cap their width at approximately 65ch (≈ 720px at 16px/1ch).…

typography ↗ 5 · q4.0

Line Length Optimal

Body text containers (paragraphs, list items, block quotes) MUST limit measure (line length) to between 45 and 75 characters per line.…

typography ↗ 9 · q4.0

Form Validation Inline

Form fields MUST be validated and feedback rendered at field `blur` (or after the user has clearly committed to a value), NOT only on submit.…

usability ↗ 12 · q4.0

Missing Empty State

Rendering an empty container — a blank table, an unstyled `<div>`, or just the page chrome with nothing inside — when a list, search, or workspace returns zero items.…

ux-design ↗ 4 · q4.0

No Loading State

Triggering an async fetch, mutation, or navigation without any visible feedback — no spinner, skeleton, optimistic update, or disabled button.…

ux-design ↗ 4 · q4.0

Counter Example Button No Loading

A typical submit handler that awaits a network request without any visible feedback. The button stays enabled, no spinner appears, the user can click it five times and trigger five duplicate POSTs.

Counter Example Empty List Blank

A React issue-list component that renders a `<ul>` with `items.map(...)`. When `items` is an empty array, the component renders an empty `<ul>` and the page goes silent. No headline, no CTA, no explanation.

Consistency Standards

Nielsen Heuristic 4 — Consistency and Standards: Users should not have to wonder whether different words, situations, or actions mean the same thing. Follow platform and industry conventions.

Error Prevention

Nielsen Heuristic 5 — Error Prevention: Even better than good error messages is a careful design which prevents a problem from occurring in the first place.…

Flexibility Efficiency

Nielsen Heuristic 7 — Flexibility and Efficiency of Use: Accelerators — unseen by the novice user — may often speed up the interaction for the expert user such that the system can cater to both inexperienced and experien…

Match Real World

Nielsen Heuristic 2 — Match Between System and the Real World: The system should speak the users' language, with words, phrases, and concepts familiar to the user, rather than system-oriented terms.…

Recognition Over Recall

Nielsen Heuristic 6 — Recognition Rather Than Recall: Minimize the user's memory load by making objects, actions, and options visible.…

ux-design ↗ 4 · q4.0

User Control Freedom

Nielsen Heuristic 3 — User Control and Freedom: Users often choose system functions by mistake and will need a clearly marked 'emergency exit' to leave the unwanted state without having to go through an extended dialogue…

Visibility System Status

Nielsen Heuristic 1 — Visibility of System Status: The system should always keep users informed about what is going on, through appropriate feedback within a reasonable time.

Nielsen Aesthetic

Dialogues should not contain irrelevant or rarely needed information. Every extra unit of information in a dialogue competes with the relevant units of information and diminishes their relative visibility.

Nielsen Consistency

Users should not have to wonder whether different words, situations, or actions mean the same thing. Follow platform conventions.

Nielsen Error Prevention

Even better than good error messages is a careful design which prevents a problem from occurring in the first place.…

Nielsen Error Recovery

Error messages should be expressed in plain language (no codes), precisely indicate the problem, and constructively suggest a solution.

Nielsen Flexibility

Accelerators — unseen by the novice user — may often speed up the interaction for the expert user such that the system can cater to both inexperienced and experienced users. Allow users to tailor frequent actions.

Nielsen Help

Even though it is better if the system can be used without documentation, it may be necessary to provide help and documentation.…

Nielsen Real World Match

The design should speak the users' language. Use words, phrases, and concepts familiar to the user, rather than internal jargon. Follow real-world conventions, making information appear in a natural and logical order.

Nielsen Recognition

Minimize the user's memory load by making objects, actions, and options visible. The user should not have to remember information from one part of the dialogue to another.…

Nielsen User Control

Users often choose system functions by mistake and will need a clearly marked 'emergency exit' to leave the unwanted state without having to go through an extended dialogue. Support undo and redo.

Nielsen Visibility

The system should always keep users informed about what is going on, through appropriate feedback within reasonable time.

ux-design ↗ 10 · q4.0

Taxonomy Empty States

A taxonomy of empty states by their underlying cause. Each cause requires distinct UX: 'no data yet' invites action; 'cleared' celebrates progress; 'error' explains failure; 'filtered to nothing' offers escape.…

ux-design ↗ 5 · q4.0

Taxonomy Form Validation States

A taxonomy of form-field validation states by severity and timing. Each state has distinct visual treatment, ARIA semantics, and lifecycle rules.…

ux-design ↗ 6 · q4.0

Taxonomy Loading States

A taxonomy of loading states by perceived duration. Different durations require different visual treatments: instant operations need no indicator at all; sub-second waits show progress in-context; multi-second waits need…

ux-design ↗ 6 · q4.0

source @nielsen

Source Nielsen 1994

The foundational text establishing Nielsen's 10 usability heuristics for interface design. Chapter 5 defines the heuristics used in expert review (heuristic evaluation).…

taxonomy @nielsen

Taxonomy 10 Heuristics

Jakob Nielsen's ten general principles for interaction design, derived from factor analysis of 249 usability problems. Used as the evaluation framework in heuristic review sessions.…

ux-design ↗ 10 · q4.0

Rainbow Explosion

Applying five or more distinct hue families (e.g., red badges, orange warnings, yellow highlights, green successes, blue links, purple headings, teal cards) in a single product UI without a systematic hierarchy — produci…

Category Button Hierarchy

The hierarchical grouping of button styles within a UI surface. Hierarchy clarity — which action is the primary, which is alternative, which is optional — is the single most important driver of action discoverability.…

Category Form Input States

The visual states an input control passes through during user interaction. A complete form-input system specifies the visual treatment for each state and the transitions between them. Incomplete state coverage (e.g.…

Category Layout Grid

Grid-based layout patterns for UI composition. This category covers CSS Grid usage patterns, column systems, gutter strategies, and responsive breakpoint behavior.

Category Typography Scale

The typographic scale sub-category covers all decisions about relative and absolute type sizes across the interface: base size selection, scale ratio, display headings, body text, captions, and code.

Check Color System Preflight

Preflight checklist for a complete color system: validates hue spread ≥ 120° between primary and accent, chroma difference ≥ 0.04, dark-mode backgrounds at L ≥ 0.08 (not pure black), steps 9–10 contrast ≥ 4.…

Constraint Brand Hue Required

Brand color systems must derive their primary ramp from a single OKLCH hue (one --hue variable feeding 9–12 lightness stops at calibrated chroma).…

Constraint Max Color Roles 7

A single product-level design system should expose at most 7 semantic color roles: bg, surface, border, text, text-muted, primary, accent.…

Constraint No Pure Black Text

Body and paragraph text must never use pure black (#000000 / oklch(0% 0 0)). Pure black on near-white induces excessive contrast and visual fatigue; use a soft near-black such as oklch(18% 0.04 var(--hue)).

Constraint No Pure White Bg

Backgrounds for long-form prose must not be pure white (#ffffff). Use a warm or cool off-white such as #f9f7f4 or oklch(98% 0.008 var(--hue)) to reduce halation and reading fatigue.

Constraint Oklch Only Color

All new color declarations must use the oklch() color function. Hex (#rrggbb), rgb()/rgba(), hsl()/hsla(), and CSS named colors are forbidden in new author code and in design tokens.

Counter Example Tailwind Blue 500

A button and link styling that uses Tailwind's default `blue-500` (#3b82f6) and `blue-600` (#2563eb) as the entire brand expression. Identical to thousands of v0 / shadcn / starter-kit landing pages.

Example Calcom Scheduler

Cal.com's booking page is a two-column layout: left side shows a month calendar grid with available days as filled circles in #292929 (dark mode) or solid black (light mode); right side shows time slots as a vertical lis…

Example Catalyst App

Catalyst is Tailwind's premium app UI kit. Unlike basic Tailwind UI, Catalyst uses a refined zinc-neutral palette with rounded-xl (12px) cards, soft shadows, and a distinctive 'glass' navbar with backdrop-blur.…

Example Linear Cmdk

Linear's Cmd+K palette opens as a centered modal at ~640px wide on a translucent dark overlay (#000 at 40% alpha + 8px backdrop-blur).…

Example Linear Issues Table

Linear's primary issue list is a single-line-per-row table on a near-black canvas (#08090A). Each row shows: priority icon (4 bars), issue ID (e.g.…

Example Linear Kanban

Linear's board view shows columns (Backlog / Todo / In Progress / Done) with subtle column headers and stacked cards.…

Example Mercury Banking Dashboard

Mercury's banking dashboard sits on a near-white #FAFAF7 background (warm tint, not pure gray).…

Example Notion Blocks

When a Notion page is empty, the editor shows a single placeholder line ('Type / for commands') in #9B9A97 italic.…

Example Notion Cmdk

Notion's Cmd+P (Quick Find) opens a centered modal on a light cream background (#FFFFFF over a 50% rgba(15,15,15,0.5) backdrop) with results grouped by recency: 'Last visited' first, then 'Other'.…

Example Notion Sidebar

Notion's sidebar is a 240px-wide rail in cream #F7F6F3 showing a tree of nested pages. Each page row is 28px tall with a 14px chevron (collapsed/expanded), 18px emoji/icon, and 14px text in #37352F.…

Example Plaid Connect

Plaid Link is a multi-step modal (max-width 380px, fixed height ~600px) embedded via iframe.…

Example Resend Dashboard

Resend's email logs page shows a single dense table on a #0A0A0A background: timestamp (#71717A monospace), 'To' address (#FAFAFA), subject (truncated), status pill (delivered green / opened blue / bounced red), and a sm…

Example Resend Hero

Resend's homepage opens with a 64px headline ('Email for developers') in white on near-black #0A0A0A, paired with a live code sample on the right showing a Node.js snippet of `resend.emails.send(...)`.…

Example Shadcn Dashboard

The shadcn dashboard template uses HSL CSS variables for theming with a 240-deg neutral palette.…

Example Shadcn Settings

shadcn's settings example is a two-pane layout: left navigation list (Profile / Account / Appearance / Notifications / Display) at 200px, and main pane at max-width 600px.…

Example Stripe Checkout

Stripe Checkout renders a two-column layout: left side (~480px) shows the merchant's logo and an itemized summary on a #FAFBFC background; right side (~520px) is the payment form on white #FFFFFF with email input, card f…

Example Stripe Dashboard

The Stripe Dashboard combines KPI cards (Volume, Net Volume, Successful Payments) at the top with a stacked-bar timeseries chart in Stripe purple #635BFF, then a payments table below showing amount, customer, status pill…

Example Stripe Pricing

Stripe's pricing page is a light-mode (#FFFFFF) layout showing each Stripe product (Payments, Billing, Connect) as a tall card with a colored gradient header (purple #635BFF for Payments, teal #00D4FF for Billing), produ…

Example Tailwindui App Shell

Tailwind UI's stacked + sidebar app shell uses a 240px left sidebar with vertical nav (icon + label rows), a 64px top bar with search + profile dropdown, and a main content area with max-width 7xl (1280px).…

Example Tailwindui Marketing

Tailwind UI's marketing layouts use a centered-column structure (max-width 1280px) with a hero featuring 56px headline in indigo gradient text, alternating feature sections (image-left / text-right and reverse), pricing …

Example Vercel Analytics

Vercel Analytics shows Core Web Vitals (LCP, FID, CLS, INP) as four large stat cards with the metric value in 32px white, a delta indicator (green up arrow / red down arrow), and a 80px-tall sparkline chart underneath in…

Example Vercel Dashboard

The Vercel project dashboard renders deployments as a vertical list with each row showing: status dot (green #0CCE6B / yellow #F5A623 / red #EE0000), commit message in 14px white, branch name as a #A1A1A1 chip, author av…

Example Vercel Hero

Vercel's homepage opens with a tightly-kerned headline ('Your complete platform for the web') in white Geist Sans on a #000 background, followed by a sub-headline in #A1A1A1, twin CTAs (primary white, secondary outlined)…

Example Vercel Pricing

Vercel's pricing page presents three plans (Hobby, Pro, Enterprise) as side-by-side cards on a near-black canvas (#000) with the middle Pro tier elevated by a subtle 1px white border at ~12% alpha and a 'Recommended' eye…

Example Vercel Sidebar

The Vercel dashboard sidebar transitions between expanded (240px) and collapsed (56px) states using a CSS `width` transition with `overflow: hidden` on the nav container.…

Feedback Dark Mode Rollout

Lessons from shipping dark-mode support across multiple production design systems.…

Persona Airbnb

Warm photography-forward marketplace aesthetic: Airbnb Cereal VF in the 500-700 weight range, Rausch Red #ff385c as the single accent on pure white, with 20-32px radius cards that invite touch and three-layer shadow elev…

Persona Apple

Cinematic product-as-sculpture marketing aesthetic: SF Pro Display/Text with optical sizing crossover at 20px, pure-black #000000 and cool-tinted #f5f5f7 alternating in binary film-cut rhythm, Apple Blue #0071e3 as the s…

visual-design ↗ 24 · q4.0

Persona Coinbase

Institutional crypto-financial aesthetic: CoinbaseDisplay/Sans/Text/Icons proprietary four-font stack, Coinbase Blue #0052ff as sole accent on white and near-black #0a0b0d, 56px pill CTAs with a counterintuitive hover-li…

Persona Figma

Achromatic tool-chrome aesthetic: figmaSans variable font with granular weight stops (320–700), strict black #000000 and white #ffffff interface shell hosting explosively colorful product-output heroes, pill and circle b…

Persona Framer

Dark-first cinematic tool aesthetic: GT Walsheim at 500 weight only with extreme -5.…

Persona Intercom

Warm editorial B2B platform: Saans on cream-white #faf9f6 canvas, Fin Orange #ff5600 as singular AI accent, and near-rectangular 4px button radius that creates industrial precision against cozy warm neutrals.

Persona Linear

Dark-mode-native project management precision: Inter Variable at weight 510 with cv01/ss03 OpenType features on near-black #08090a, single indigo #5e6ad2 accent, and translucent rgba(255,255,255,0.…

Persona Mintlify

Documentation-as-product design: Inter on pure white #ffffff with atmospheric green-to-white gradient hero, brand green #18E299 reserved exclusively for interactive states, full-pill 9999px buttons and inputs, and whispe…

Persona Notion

Warm minimalist workspace brand: NotionInter (modified Inter) on pure white #ffffff with warm-undertone gray scale, Notion Blue #0075de as single saturated accent, whisper borders at rgba(0,0,0,0.…

Persona Posthog

Anti-corporate open-source analytics: IBM Plex Sans at 700/800 on sage-tinted parchment #fdfdf8, PostHog Orange #F54E00 hidden until hover, hand-drawn hedgehog illustrations replacing stock photography, and an olive-gree…

Persona Raycast

macOS-native precision instrument: near-black blue-tinted void #07080a with Inter + GeistMono, layered multi-layer inset box-shadows simulating pressed-glass depth, and Raycast Red #FF6363 reserved exclusively for the di…

Persona Replicate

Festival-energy AI platform: rb-freigeist-neue 700 at 128px manifesto scale on a white canvas with explosive orange #ea2804→magenta hero gradient, and 9999px pill radius applied absolutely to every element without except…

Persona Sanity

Nocturnal command center: pure-achromatic gray ramp on near-black #0b0b0b, waldenburgNormal at -4.…

Persona Sentry

Late-night debugging aesthetic: warm purple-black #1f1633 canvas with bioluminescent inset-shadow buttons, Dammit Sans hero voice contrasted by Rubik UI workhorse, and lime green #c2ef4e as rare high-visibility pop again…

Persona Spotify

Content-first darkness: near-black cocoon #121212 where album art is the sole color source, SpotifyMixUI at bold-or-regular binary weight contrast, Spotify Green #1ed760 reserved for play controls only, and pill-plus-cir…

Persona Stripe

Premium fintech marketing aesthetic: weight-300 sohne-var headlines on pure white with deep navy #061b31 headings, saturated purple #533afd CTAs, and blue-tinted multi-layer shadows that signal financial-grade confidence…

Persona Supabase

Dark-mode-native BaaS developer aesthetic: Circular weight 400 at 1.00 line-height on near-black #171717 with PostgreSQL-green #3ecf8e as identity-only accent, depth built entirely from border-color stepping rather than …

visual-design ↗ 24 · q4.0

Persona Superhuman

Luxury-productivity aesthetic: Super Sans VF at non-standard weight 540 / line-height 0.…

Persona Vercel

Achromatic minimalism as engineering principle: Geist Sans with extreme -2.4px to -2.…

Persona Warp

Warm-dark developer lifestyle aesthetic: Matter Regular at weight 400 even on headlines, near-black canvas with earthy warm-gray undertones (not cold blue-black), #faf9f6 Warm Parchment text, and nature photography inter…

Provocation Contrast Intent

@community/provocation-contrast-intent

Animation Duration

UI motion (hover, focus, expand, collapse, page transition) MUST resolve in 100–300ms. Below 100ms the motion reads as a glitch; above 300ms it feels sluggish; above 500ms users perceive the UI as broken. Cap is 500ms.

visual-design ↗ 9 · q4.0

visual-design ↗ 11 · q4.0

Color Blacklist Brand

Forbids the canonical AI-slop color palette — Inter-purple (#6366F1 / oklch(60% 0.20 280)), pure black (#000) on pure white (#fff) body, and the default browser blue link (#0000EE / #1A0DAB) — from production artifacts.…

Color Dark Mode Cascade

Dark mode MUST be implemented via a CSS-cascade strategy keyed on `@media (prefers-color-scheme: dark)` or a single root-level `[data-theme='dark']` selector that flips token values.…

visual-design ↗ 9 · q4.0

visual-design ↗ 11 · q4.0

Color Oklch Required

All new color declarations in CSS / inline styles MUST use the oklch() color function.…

Font Blacklist Applied

The primary display and body typefaces in author CSS MUST NOT be drawn from @impeccable/constraint-font-blacklist (Inter, Roboto, Arial, Helvetica Neue, Space Grotesk, DM Sans, Nunito, Poppins, Open Sans, Lato).…

visual-design ↗ 7 · q4.0

Grid Baseline Aligned

Long-form text and adjacent typographic elements (captions, metadata, sidebars) MUST share a vertical baseline grid — the typographic baseline of one block aligns with another at a consistent rhythmic interval.…

visual-design ↗ 6 · q4.0

visual-design ↗ 10 · q4.0

Spacing Rhythm

All vertical spacing (margin, padding, gap) MUST be drawn from a single 8-point scale: 4, 8, 12, 16, 24, 32, 48, 64, 96, 128 px (or rem equivalents).…

Taxonomy Cta Styles

A taxonomy of button styles by hierarchy and intent. Distinct visual treatments are how a UI signals which action is primary, secondary, optional, or destructive. Conflating these styles (e.g.…

Taxonomy Typography Roles

A classification of typographic roles in digital product interfaces. Each role carries distinct size, weight, and spacing requirements.…

visual-design ↗ 6 · q4.0

Leading

The vertical distance between successive baselines of text — historically the height of the lead strips inserted between lines of metal type.…

Oklch

A perceptually-uniform polar color space (Lightness, Chroma, Hue) built on the Oklab color model, standardized in CSS Color Level 4. Each channel has an intuitive meaning: L (0–1) is perceived lightness; C (≈ 0–0.…

Rasterization

The process by which vector graphics, font glyphs, and CSS-defined shapes are converted into a pixel grid for display.…

Density Vs Comfort

The fundamental tension in UI layout: dense layouts maximize information per viewport but increase cognitive load and require expert familiarity; comfortable layouts reduce stress and speed comprehension but reduce scann…

Transform Hex To Oklch

Converts a hex color string ('#3B82F6' or '3B82F6' or '#fff') to oklch coordinates. Composes hex parsing → sRGB → linear sRGB → XYZ D65 → Oklab → polar oklch.…

Transform Px To Rem

Converts a CSS pixel value to its rem equivalent relative to the root element font-size (default 16px).…

Transform Rgb To Oklch

Converts an sRGB color to oklch() coordinates via linear sRGB → XYZ D65 → Oklab → polar oklch.…

Transform Scale Clamp

Generates a CSS `clamp()` expression for fluid typography or spacing that linearly interpolates between minSize at minVp viewport width and maxSize at maxVp viewport width, clamped at both ends.…

Value Brand Hue

@community/value-brand-hue

Value Content Line Length

@community/value-content-line-length

Value Motion Duration Fast

@community/value-motion-duration-fast

Value Z Index Tokens

@community/value-z-index-tokens

anti-pattern @impeccable

Ai Slop Palette

The statistically predictable default visual language produced by AI code generation tools when given no specific brand constraints: Inter typeface + saturated purple (#7c3aed–#8b5cf6) + near-black background + rounded c…

constraint @impeccable

Constraint Font Blacklist

A list of typefaces that are banned from use as the primary display or body typeface in impeccable-quality frontend design because they are statistically over-represented in AI-generated interfaces and commodity template…

counter-example @impeccable

Counter Example Inter Purple Dark

A statistically over-represented combination in AI-generated frontends: Inter as the typeface, a saturated purple (#7c3aed or similar) as the brand accent, on a near-black (#0f0f0f or #111827) background.…

Persona Brutalist

Raw concrete made digital: exposed structure, monospaced everywhere, harsh hierarchy, default browser blue links, intentionally awkward layouts that refuse polish.…

Persona Dense Pragmatist

An aesthetic persona derived from professional-grade data tools: Bloomberg Terminal, trading dashboards, IDE UIs, analytics platforms.…

Persona Editorial

An aesthetic persona derived from high-quality editorial publishing: newspapers, literary magazines, annual reports.…

Persona Magazine Editorial

The web translation of Wired, NYT Magazine, and Pitchfork: oversized display serifs at 96-160px, drop caps, asymmetric multi-column flow, full-bleed photo essays, small-caps section heads, byline-dateline-photo-credit ty…

Persona Notion Warm

Friendly productivity-tool aesthetic: off-white #fbfaf9 paper background, soft warm-grey borders, Inter or SF Pro Display, callout cards with emoji, generous block spacing, hover states that feel tactile.…

visual-design ↗ 30 · q4.0

Persona Stripe Fintech

Fintech trustworthiness made aspirational: brand-color OKLCH systems with a single hue variable, animated gradient hero backgrounds, dense API-doc tables, rounded 12px cards with crisp 1px hairline borders, dark-mode tog…

Persona Swiss Modernist

Müller-Brockmann on the web: mathematical baseline grids, neo-grotesque display set tight, ruled horizontal lines, asymmetric typographic compositions, one accent color in a sea of neutral.…

Persona Tokyo Minimal

Japanese minimalism translated to web: extreme negative space (ma), hairline rules, soft greys on warm off-white, mixed-script typography (Noto Sans JP + Inter), tatami-grid spatial logic.…

visual-design ↗ 29 · q4.0

Persona Vercel Clean

Dark-first developer-tool aesthetic: Geist Sans on near-black OKLCH neutrals, generous whitespace, monochrome surfaces lifted by subtle radial gradients, one neon accent (cyan/magenta/lime), and crisp 1px borders on glas…

Persona Warm Institutional

The visual language of public libraries, university presses, and museum websites: serif body text on cream paper, sans display, terracotta and forest accents, generous block padding, footer columns thick with credits and…

visual-design ↗ 10 · q4.0

principle @impeccable

Distinctiveness

A designed artifact should be immediately distinguishable from the average output of the tools used to create it.…

provocation @impeccable

Provocation Why Not Serif

@impeccable/provocation-why-not-serif

Template Oklch Palette

Generates a full 10-step tonal palette in oklch() for a brand color, with dark-mode variants. Steps are perceptually even due to oklch's uniform lightness axis. Each step includes a semantic role comment.

Api Gateway

An API Gateway is a single ingress that fronts the microservice fleet. Clients (web, mobile, partner) talk to one URL; the gateway routes to internal services, fans out parallel calls, aggregates responses, terminates TL…

Circuit Breaker

A service that calls a remote dependency wraps the call in a circuit breaker. After a threshold of failures, the breaker trips OPEN and short-circuits subsequent calls — they fail immediately without hitting the network.…

backend-architecture ↗ 3 · q4.0

Cqrs

Command Query Responsibility Segregation. The model that handles writes (commands) is separated from the model(s) that handle reads (queries).…

Database Per Service

Each microservice has a private database. No other service reads or writes that database directly — they go through the owning service's API. The schema is an internal implementation detail, free to evolve.…

Saga

When a business transaction must update data in multiple services, you cannot use a single ACID transaction across them (no distributed XA).…

backend-architecture ↗ 3 · q4.0

Service Registry

In a dynamic environment (containers come and go, instances autoscale), service hostnames are not known ahead of time.…

Backing Services Attached

Backing services are URLs in env, not addresses in code. The app does not know if its database is on the same host or across the planet.

Build Release Run

Build → Release → Run are three stages that flow one direction. No mutation in production.

backend-architecture ↗ 2 · q4.0

Codebase One Per App

One app, one repo. If you have two apps in one repo, split them. If you have one app in two repos, merge them.

Concurrency Process Model

Scale out, not up. Each process type is a horizontally-scalable share-nothing unit.

Config In Environment

Strict separation of config from code. Config lives in the environment, not the repo.

backend-architecture ↗ 3 · q4.0

Dependencies Explicit

Declare every dependency. Isolate at runtime. Never lean on system-wide installs.

Dev Prod Parity

Close the gap between dev and prod on time, people, and tools.

Disposability

Start fast. Shut down gracefully. Tolerate sudden death.

Admin As One Off Processes

DB migrations, console sessions (REPL into prod data), one-off scripts (`scripts/import.js`) — all run as one-off processes against an identical release of the same codebase.…

backend-architecture ↗ 2 · q4.0

Logs As Event Streams

The app writes its event stream, unbuffered, to stdout. It does not concern itself with routing or storage. The execution environment captures the stream and routes it to log indexers, archives, or analytics.…

backend-architecture ↗ 2 · q4.0

Port Binding

The app is self-contained — it does not require a runtime injection of a webserver (Apache, nginx) into the execution environment.…

backend-architecture ↗ 5 · q4.0

Stateless Processes

App processes are stateless and share-nothing. Any data that must persist is stored in a stateful backing service (database, cache, object store).…

collection @security

Owasp Appsec Starter

A 27-atom seed set distilled from the OWASP Cheat Sheet Series — the controls a web application must implement before any other security work is meaningful: input validation, authentication, session management, cryptogra…

general ↗ 30 · q4.0

persona @security

Persona Security Auditor

The auditor's lens: assume the worst plausible attacker, enumerate trust boundaries, demand evidence rather than assurances, and produce a ranked findings list with concrete remediations and OWASP references.

Concatenate Sql Strings

Constructing a SQL statement by concatenating, interpolating, formatting, or templating data into the query text. Any technique where the resulting query string contains values that originated outside the source code.

Hardcode Secrets

Embedding API keys, database passwords, signing keys, or other secrets directly in the source repository, in tracked config files (`config.yml`, `application.properties`, `secrets.…

Render Untrusted Html

Taking a string that came (directly or transitively) from a user and inserting it into the DOM as HTML — via `element.innerHTML = …`, React `dangerouslySetInnerHTML`, Vue `v-html`, Svelte `{@html …}`, or `document.…

Roll Your Own Crypto

Implementing a cipher, hash, MAC, or 'lightweight encryption scheme' from scratch instead of using a vetted library.…

Session Id In Url

Carrying the session identifier in the URL — query string, path segment, or fragment — instead of in a cookie.…

State Change On Get

Routes that perform side effects — delete, transfer, subscribe, like, vote, fire-the-missiles — in response to a GET.…

Store Passwords Reversibly

Storing passwords as plaintext, encrypted (any reversible cipher), with a fast hash (MD5, SHA-1, SHA-256), or unsalted.…

Trust Client Input

Relying on JavaScript validation, hidden form fields, disabled buttons, or HTTP headers set by the user agent to enforce a security or correctness invariant. Every byte the client sends is attacker-controlled.

Check Csp Header Set

@security/check-csp-header-set

Check Input Canonicalised Before Validation

@security/check-input-canonicalised-before-validation

Check Multi Factor Authentication Enforced

@security/check-multi-factor-authentication-enforced

Check No String Concat In Queries

@security/check-no-string-concat-in-queries

Check Origin Or Referer Validated

@security/check-origin-or-referer-validated

Check Session Id Rotated On Login

@security/check-session-id-rotated-on-login

Check Tls Configuration Modern

@security/check-tls-configuration-modern

principle @security

Defense In Depth

Assume every individual control will fail at some point. Design so that the system survives any single failure: a successful XSS hits a session cookie that is HttpOnly; a leaked database has bcrypt'd passwords; a stolen …

principle @security

Least Privilege

If the role doesn't need to read PII, deny it. If the service doesn't need to write to S3, deny it. If the database account doesn't need DROP, deny it.…

Csrf Token On State Changing Requests

Any request that changes server state — POST, PUT, PATCH, DELETE — must be authenticated with something an attacker cannot forge from another origin.…

Encode Output By Context

Untrusted data rendered into HTML must be encoded for the specific syntactic context where it lands: HTML body, HTML attribute, JavaScript string, URL, CSS value.…

Encrypt Data At Rest With Aead

Sensitive data at rest must be encrypted with an authenticated cipher mode (AEAD) — AES-256-GCM, ChaCha20-Poly1305, or AES-SIV. Never use raw AES-CBC, ECB, or any unauthenticated mode.…

Hash Passwords With Argon2 Or Bcrypt

User passwords must be stored using a deliberately slow, salted, adaptive hash designed for password storage: argon2id (preferred), scrypt, or bcrypt.…

Parameterize Sql Queries

Every SQL query that includes any data — user input, configuration, computed values, anything not a literal in the source — must use parameterised queries (prepared statements) where the SQL structure is fixed and the va…

Session Cookie Secure Flags

Every cookie that carries a session identifier or auth token must be issued with `Secure`, `HttpOnly`, and `SameSite=Lax` (or `Strict`).…

Store Secrets In Vault

Database passwords, API keys, signing keys, OAuth client secrets, and TLS private keys must be retrieved at runtime from a managed secrets store (HashiCorp Vault, AWS Secrets Manager, GCP Secret Manager, Azure Key Vault,…

Validate Input Server Side

Every value that enters trust boundaries — request body, query string, headers, cookies, file uploads, message-queue payloads — must be validated server-side before it influences a decision, query, or write.…

value @security

Value Input Validation Allow List

@security/value-input-validation-allow-list

Import For Side Effects

Writing `import './polyfills'` or `import 'register-handlers'` to trigger code execution at module load.…

Mutable Named Export

Declaring `export let counter = 0` (or similar) and then reassigning it elsewhere in the module so importers' references update with each change.…

Reassign Parameters

Treating a parameter as a mutable local — assigning to it, mutating its properties when the caller did not opt in, or using it as scratch space.…

Use Var

Using `var` to declare any binding in modern JavaScript or TypeScript. `var` is hoisted to the enclosing function, has no temporal-dead-zone protection, and is silently re-declarable — three properties that exist only be…

principle @web-style

Clarity Over Cleverness

When a clever idiom and an obvious idiom both work, pick the obvious one. Save the cleverness for the cases where it earns its keep — performance hot paths backed by benchmarks, language-level constraints that allow no o…

principle @web-style

Consistency Within Codebase

Local consistency outranks personal preference. If the existing code uses arrow functions everywhere, the new arrow function is correct even if you would have written `function`. If the codebase imports from `.…

Arrow Functions For Callbacks

When the function is anonymous and passed inline as an argument or assigned to a binding, use an arrow function.…

Camelcase Variables And Functions

Local variables, parameters, function names, methods, and non-static class fields are written in `camelCase` — first word lowercase, every subsequent word capitalised, no underscores or hyphens.…

Default Parameters Not Mutate Args

Express defaults in the parameter list with `=`. Do not patch missing values inside the body with reassignment, `||`, or by writing into `arguments`.…

Descriptive Not Abbreviated Names

Identifier length follows information content. Use whole words that describe the role of the binding.…

Destructure Objects And Arrays

When a function reads more than one property of an object — its parameter, its return value, or any local — pull them out with destructuring.…

Group Const Then Let

Within a scope, list every `const` binding before any `let` binding. The reader can then scan the top of the scope and immediately see which bindings are fixed and which will mutate, without re-checking each line.

Named Imports Stable Paths

Use `import { foo, bar } from './lib'` rather than `import lib from './lib'` followed by `lib.foo` and `lib.bar`.…

Object Shorthand And Computed Keys

Build objects with the most expressive ES2015+ syntax available at the literal: shorthand for properties whose key matches the source variable, method shorthand for inline methods, and computed-key syntax (`{ [expr]: val…

One Binding Per Declaration

Write `const a = 1; const b = 2;` rather than `const a = 1, b = 2;`. One declaration per binding makes diffs cleaner, lets you initialise each from a different expression without contortions, and avoids the trap of accid…

Pascalcase Classes And Types

Names for things that produce instances or describe shapes — classes, constructor functions, TypeScript types, interfaces, and enum names — are written in `PascalCase`: every word capitalised including the first.

Prefer Const Over Let

Declare every binding with `const` by default. Reach for `let` only when the binding is genuinely reassigned.…

Prefer Functional Array Methods

When iterating an array to produce a derived value — a new array, a single accumulator, the first match, a boolean — use the corresponding higher-order method.…

Prefer Spread Over Apply

When passing a list of values as positional arguments, spread the array (`fn(...args)`) instead of calling `fn.apply(null, args)`. When collecting variadic arguments, use rest parameters (`function fn(...…

Uppercase Snake For True Constants

Reserve `UPPER_SNAKE_CASE` for top-level program-wide constants whose value is fixed for the lifetime of the program and is also a primitive or deeply frozen value.…

anti-pattern @android-compose

Side Effects In Composables

Putting impure work — `viewModel.fetchUser()`, `analytics.log("viewed")`, `scope.launch { ... }`, or `someState.…

pattern @android-compose

Edge To Edge Insets

On Android 15+ activities are edge-to-edge by default — content draws behind the status bar and navigation bar, all the way to the screen edges.…

pattern @android-compose

Predictive Back

On Android 13+ predictive back lets users peek at the destination during the back-gesture: as the user drags from the screen edge, the OS shows a preview of where they'll land.…

pattern @android-compose

Responsive Via Window Size Class

Read the current window dimensions through `currentWindowAdaptiveInfo()` and switch layout topology by `WindowWidthSizeClass` (Compact / Medium / Expanded) and `WindowHeightSizeClass`. Compact = phone portrait (1-pane).…

principle @android-compose

Recomposition As Source Of Truth

Recomposition is the source of truth, not the developer's intuitions about call frequency.…

android-compose ↗ 4 · q4.0

principle @android-compose

State Driven Ui

Treat every screen as a pure projection of a State object onto pixels. Inputs (clicks, text, gestures) update the State; the State drives the projection; the projection is the UI.…

android-compose ↗ 4 · q4.0

Avoid Recomposition Via Remember

A composable's body re-runs on every recomposition. Anything allocated or computed at the top level of the body — a parser, a Regex, a sorted list, a formatted string — runs every recomposition unless wrapped in `remembe…

Color Roles Not Raw Hex

Material 3 defines 30+ semantic color *roles* — `primary`, `onPrimary`, `surface`, `onSurfaceVariant`, `error`, `outline`, etc. — exposed in Compose as `MaterialTheme.colorScheme.<role>`.…

Composable Annotation Not Raw Fn

A function that emits Compose UI or invokes other @Composable functions must itself be marked @Composable.…

Content Description Non Decorative

TalkBack reads `contentDescription` aloud when focusing an image or icon. Every non-decorative visual that conveys information OR is the only label for an action must have a non-empty `contentDescription`.…

Elevation Tokens

Material 3 elevation is expressed via six tokens — `level0` (0dp) through `level5` (12dp) — that map to BOTH a shadow elevation and a tonal-color overlay drawn on top of `surface`.…

android-compose ↗ 4 · q4.0

Hoist State Up

A composable that displays a piece of state should NOT own it. Owning means calling `remember { mutableStateOf(...) }` inside the composable that renders.…

Modifier As First Optional Param

Every component composable that emits layout exposes a `modifier: Modifier = Modifier` parameter. It comes after all required parameters and before all other optional ones.…

Motion Easing Tokens

Material 3 motion is built on a small set of named easing curves and duration tokens — `MotionTokens.EasingEmphasizedCubicBezier`, `EasingStandardCubicBezier`, durations `Short1` (50 ms) through `ExtraLong4` (1000 ms).…

No Side Effects In Composables

A @Composable function's body is called by the runtime on a schedule it controls — many times per second during animations, possibly with stale snapshots, possibly aborted half-way.…

Prefer Stable Keys In Lazy Column

`LazyColumn`, `LazyRow`, and `LazyVerticalGrid` use the `key` parameter on each item to identify it across recompositions.…

Semantic Tree Via Modifier Semantics

The Compose accessibility tree is what TalkBack and ui-test see. By default it mirrors the composable tree, but custom widgets, merged groupings, and dynamic state often need explicit shaping via `Modifier.…

Single Source Of Truth

Every value that drives the UI lives in exactly one place — a ViewModel, a remembered state holder, or a state-hoisted parameter. Composables read it and emit it.…

Slot Content Via Composable Lambda

When a component has a region the caller might want to customise — header, leading icon, trailing action, body — expose that region as a `@Composable () -> Unit` parameter (a 'slot'), not as a typed config object or a St…

Touch Target 48dp

Any element a user can tap, click, or long-press — buttons, icon buttons, list rows, switches, links — must have a hit area of at least 48 dp by 48 dp.…

Typography Scale Tokens

Material 3 defines a 15-step type scale across five role families — `displayLarge/Medium/Small`, `headlineLarge/Medium/Small`, `titleLarge/Medium/Small`, `bodyLarge/Medium/Small`, `labelLarge/Medium/Small` — exposed as `…

anti-pattern @ios-swift

Never Force Unwrap Publicly

Reaching for `!` on an `Optional` whose value originates from input — a network response, user input, an `Info.…

principle @ios-swift

Clarity At Call Site

Clarity at the point of use is your most important goal. Code is read far more often than it is written. Strive to make the call site of every API a grammatical English phrase that documents its own intent.…

ios-swift ↗ 5 · q4.0

principle @ios-swift

Swift As Progressive Disclosure

Build APIs and code in the same shape: the common case is a one-liner; the next-most-common case adds one explicit modifier; only the genuinely complex case pulls in the full machinery.…

ios-swift ↗ 5 · q4.0

Await Not Completion Handler

New async APIs are written as `func f(...) async throws -> T`. The call site reads as straight-line code, errors propagate through `try`, cancellation propagates through the cooperative cancellation system, and the struc…

Clarity At Call Site

Code is read far more often than it is written. Every naming and signature decision — argument labels, method vs.…

ios-swift ↗ 4 · q4.0

Error Throws Not Result Where Possible

Swift has two error-handling shapes: throwing functions (`func f() throws -> T`, `func f() async throws -> T`) and `Result<Success, Failure>`.…

Guard Let Early Return

When the rest of a function does not make sense without a particular optional being non-nil, write `guard let x = optionalX else { return ... }`.…

Label Args By Grammar

Argument labels exist to make the call site readable. The decision rule: read the call as English. (1) When the argument is the direct object of a verb method, omit the label: `removeAll()`, `view.add(subview)`.…

Name By Role Not Type

A name should describe what a value *is for*, not what its concrete type happens to be.…

Names Of Side Effects End Imperative

The grammar of a method name signals whether it mutates. Mutating methods use imperative verb phrases: `array.sort()`, `set.insert(x)`, `string.append("!")`.…

Omit Needless Words

Every word in a name should carry information at the call site. Words that merely repeat type information already present in the signature are noise: `removeElement(_ element: Element)` is `remove(_ element: Element)`.…

Optional Chaining Over Nil Check

When the goal is 'do this only if the value is present, otherwise produce nothing or a default', Swift gives three short-circuiting forms that are clearer than an `if x != nil` check followed by a body that uses `x!`.…

Prefer Method Over Fn

Free functions are reserved for cases with no obvious `self`: when the operation has no candidate primary owner, when it is a generic utility over multiple unrelated types, or when it forms part of a domain notation (e.…

Prefer Sendable

Under Swift 6 strict concurrency, any value passed across an `actor` boundary, into a detached task, or stored in `@Sendable` state must conform to `Sendable`.…

ios-swift ↗ 4 · q4.0

Protocol Vs Class When To Use

When defining a new type, ask what is being modelled. (1) A *capability* shared across unrelated concrete types → `protocol`. (2) A *value* without identity (a coordinate, a measurement, a record) → `struct` or `enum`.…

Value Types By Default

Value types — `struct`, `enum`, tuples — give Swift its data-race safety, predictable equality, and copy-on-write performance.…

Weak Self In Escaping Closures

Strong captures inside an `@escaping` closure that the receiver itself stores — completion blocks, Combine subscribers, NotificationCenter observers, async tasks held on a controller, timer handlers — create a retain cyc…