angora-design-system-audit

name	angora-design-system-audit
description	Review any component (`src/components/`), design-system page, layout specimen, or site page (`src/pages/*.astro`) against Angora's design rules — semantic token usage (no raw palette classes), `data-component` attributes, landmark vs content classification, heading ownership, flow spacing, container queries, accessibility extras not caught by `pnpm test:a11y`, and anti-patterns from `src/system.md`. Trigger whenever the user wants to audit, review, check, verify, or 'go through' existing work for violations, typically after building. Phrases like 'audit the pricing page', 'go through Button.astro', 'check the new Footer', 'run the audit', 'look over src/components/ and report violations' all trigger this.
argument-hint	["path"]

Audit: $ARGUMENTS

Before you start

1. Read src/system.md — intent, accessibility standard, anti-patterns, decisions log.
2. Read src/styles/global.css — the token definitions you're validating against.
3. Read design-principles.md — the full set of design principles informing this review.
4. Read tailwind-conventions.md — Tailwind v4 syntax rules to validate against.
5. Determine the audit scope — is the target a component (src/components/), a design system page (src/pages/design-system/), a layout (src/pages/design-system/layouts/), or a site page (src/pages/*.astro)? Some rules only apply to specific scopes (marked below). Layouts are full-page compositions — audit them like site pages (Page Rules apply) but note they use placeholder content, so skip SEO checks.

Then validate the target against the rules below.

Hard Rules (always enforced)

Tokens & Scoping

Rule	Check
Token compliance	No arbitrary values. All styling via Tailwind utility classes referencing theme tokens
Semantic token enforcement	No raw palette utility classes. Components and pages must use only semantic token classes (bg-background, bg-card, text-foreground, text-muted-foreground, border-border, bg-primary, etc.). Grep for violations: bg-gray-*, text-gray-*, border-gray-*, bg-white, text-white, bg-black, text-black, bg-primary-[0-9], text-primary-[0-9], border-primary-[0-9] (raw scale references). The primitive palette lives outside @theme so these classes shouldn't exist — but inline styles, arbitrary values (bg-[#...], text-[var(--gray-*)]), and accidental palette references still need catching. Exception: style guide page (index.astro) uses inline style attributes with var(--gray-50) etc. for palette swatches — this is intentional
Pixel translation	No hard-coded pixel values in components. User-provided pixel values should map to the nearest theme token (e.g., "32px" → spacing-8 / p-8). If no token fits, use rem for sizing and em for prose-relative spacing. Flag any arbitrary [Xpx] values
Scoping	Component styles via Tailwind classes on elements. No global CSS selectors in component files
No true black	Never #000, rgb(0,0,0), or black. Use semantic tokens (text-foreground, bg-foreground) which resolve to near-black
No generated colors	No color-mix(), lighten(), darken(), or rgba() for text on colored backgrounds. All colors from semantic tokens or explicit palette values

Component Contracts

Rule	Check
Component naming	Component names must follow the generic UI pattern, not a use case. Flag components named after their content (e.g., FAQ instead of Accordion, Testimonials instead of Carousel). The name should be reusable
data-component with flow attributes	Every component's root element has data-component="Name" (PascalCase). Sub-components too (data-component="CardBody"). Attribute appears first in the attribute list. Landmark components also set flow participation attributes (data-seamless, data-full-width) on their root element
Landmark components	Landmark components (Hero, Footer, Nav) live on their own without a Section. They render their own semantic element (<section>, <footer>, <nav>) with data-component and flow attributes. Flag landmarks wrapped in <Section>
Content components	Content components render a @container wrapper div as their root so container queries work anywhere. They do NOT compose Section internally. Flag content components that import or render Section internally
Heading ownership	Content components must not accept a heading or title prop — a parent <Section title="..."> provides the section heading. Content headings that are part of internal layout are fine as sub-components
No outer vertical margin	Landmark and content components never set margin-top/margin-bottom on their outermost element. That's the flow context's (section-flow/prose-flow) job. Flag any mt-*/mb-*/my-* on a component's root
Content props on composite shells	Composite shells must have zero content props — content flows exclusively through sub-components. Flag any string or array prop on a composite shell that represents displayable content (headings, descriptions, legal text, nav links). Even "simple" string props must be sub-components. Landmarks are not exempt
No visual content via props	Visual content flows via children and sub-components, never as props. Flag any prop that passes markup or rendered content (named slots used to pass styled markup into the shell where a sub-component should be used instead). The shell's only job is layout and behavior — content ownership belongs to sub-components
Images as <img>	All imagery uses <img> elements with object-fit: cover where needed. No CSS background-image for content images (heroes, cards, full-bleed sections). Position with absolute inset-0 inside a relative container for backdrops
States	All components interactive by default (pseudo-class variants for hover:, active:, focus-visible: + transitions). Form state prop only for non-interactive states (error, success, disabled). Composites: own variants only, child primitives in default state

ARIA & Accessibility

Contrast ratios and ARIA labeling are covered by the automated a11y test suite (pnpm test:a11y). When dark mode exists, tests run against both /view/light/* and /view/dark/* routes — each mode must independently meet AA. The audit focuses on what automated testing can't catch:

Rule	Check
Target sizes	Interactive targets ≥ 44px. Check at narrow widths too
Color independence	Don't rely on color alone to convey meaning — always a secondary indicator (icon, text, border, pattern)
EAA extras (manual)	If standard is EAA: verify text spacing override tolerance, 200% text resize. (lang and reflow are covered by the a11y test)
Dark mode contrast	If dark mode exists: verify semantic token pairs provide sufficient contrast in both modes. Check that --color-*-foreground has ≥ 4.5:1 contrast against its paired --color-* in both light and dark values. The a11y test catches most issues, but token-level mismatches (e.g., light primary text on light primary bg) need manual verification when new tokens are added

Semantic HTML

Rule	Check
Semantic elements	Content uses semantic elements (section, nav, h1–h6, p, a, button, input, figure, blockquote, ul/ol, footer). No <div> where a semantic element fits
Heading hierarchy	Heading levels don't skip (no h1 → h3). Components accept an as prop or similar for heading level flexibility

Responsive

Rule	Check
Container query syntax	Responsive variants use @sm:, @md:, @lg:, @xl: (container queries). No @media / no viewport-based sm:/md:/lg: in component markup. Only exception: design-system.css (tooling)
Responsive behavior	Component actually adapts at narrow (~320px), medium (~768px), and wide (~1280px) container widths. Check: multi-column layouts stack to single column; text doesn't overflow or clip; interactive targets stay ≥ 44px; images/media scale without breaking aspect ratio; spacing reduces proportionally at narrow widths
@container ancestor	Content components provide their own @container wrapper. Section provides @container on its root <section> element. For inline content inside Section, Section's @container is sufficient. Flag content components that use container query variants (@sm:, @md:, @lg:) but don't have their own @container wrapper

Design Rules (always enforced, require judgment)

Hierarchy

Rule	Check
Three-tier emphasis	Clear primary/secondary/tertiary emphasis using size + weight + color together
Three-tier text color	Exactly three text color tiers: text-foreground (or text-card-foreground) for primary content, text-muted-foreground for secondary/tertiary. Flag any raw grey class usage — semantic tokens enforce the correct tiers. If a third visual tier is needed, use font size or weight rather than an additional color
Font weight discipline	Only two weights: normal (font-normal/font-medium, 400–500) and bold (font-semibold/font-bold, 600–700). Flag font-thin, font-extralight, font-light (under 400)
Label treatment	Labels should be de-emphasized (smaller, lighter, thinner). Combine labels and values when possible ("12 left in stock" not "In stock: 12")
Grey on colored backgrounds	No grey text on colored backgrounds. On primary/destructive/colored surfaces, use the paired -foreground token (e.g., text-primary-foreground on bg-primary). Never use opacity-based text on colored backgrounds — it looks washed out

Spacing

Rule	Check
Proximity grouping	Related elements closer together, groups further apart. No ambiguous spacing where the relationship between elements is unclear
Generous whitespace	Err on the side of generous whitespace. Flag areas that feel cramped — especially padding inside cards, space between section heading and content

Typography

Rule	Check
Line length	45–75 characters. Use max-w-[Xch] (prefer ch units) on text containers. Constrain paragraphs independently if container has full-width elements
Line height	Proportional to font size: 1.5–1.75 for body text, 1.0–1.2 for display/heading text. Wider content may need up to 2.0
text-wrap: balance	Headings (h1–h4, display text) should have text-wrap: balance to prevent orphan lines. The prose utility applies this automatically
text-wrap: pretty	Body text (p, li, blockquote) should have text-wrap: pretty to prevent single-word last lines. The prose utility applies this automatically
Letter-spacing	Headlines should tighten tracking (tracking-tight or tracking-tighter). Small uppercase UI text (badges, eyebrows, nav labels under text-lg) should widen (tracking-wide). Display-size uppercase text (text-xl and above) keeps normal tracking — the large size already provides legibility. See system.md Conventions for the full letter-spacing policy
Center-align limits	Center-aligned text only for very short blocks (1–3 lines). Body copy and longer text must be left-aligned. Flag centered paragraphs
Tabular numbers	Numbers in tables, stats, and vertically-aligned contexts should use tabular-nums (font-variant-numeric: tabular-nums)

Color

Rule	Check
Meaning, not decoration	Color communicates meaning. Greys for structure, color for emphasis and action
Semantic color usage	Red for errors/destructive, yellow/amber for warnings, green for success. Don't repurpose semantic colors for decoration

Depth

Rule	Check
Consistent application	Similar elements at the same elevation. Light source from above. In dark mode, tonal elevation (lighter surface = higher) conveys depth — shadows have reduced visibility
Shadow interaction	Interactive elevated elements: hover increases shadow (lift), active decreases shadow (press). Flag elevated buttons/cards without shadow transitions
Fewer borders	Prefer box shadows, different background colors, or extra spacing over borders for visual separation. Flag heavy border usage where a subtler technique would work

Page Rules (site pages and layouts — src/pages/*.astro and src/pages/design-system/layouts/)

Skip this section when auditing components or design system specimen pages.

Rule	Check
Flow context	Pages use <main class="section-flow"> for inter-section spacing. Posts/articles use <article class="prose-flow">
Manual typography in content zones	Flag manual typography classes on <h2>, <p>, <a> inside content zones — prose handles these. Only flag inside section-flow or prose-flow zones where ambient prose applies
Blockquote prose protection	Blockquotes inside prose zones need protection via data-component (prose targets blockquote:not([data-component])) or explicit counter-declarations (border-l-0 pl-0 not-italic)
List prose protection	UI lists (navigation, tags, non-content lists) inside prose zones must have list-none p-0 to override prose's list styles. Content lists that should have bullets need no override
Landmark vs content wrapping	Landmark components (Hero, Footer, Nav) live on their own in section-flow — don't wrap them in <Section>. Content components sit inside <Section>
Section component	Content sections on the page use the Section component. No raw <section> elements with manual padding for content sections
Seamless usage	Sections with background colors/images use <Section seamless> (or the landmark's flow attributes). Adjacent seamless sections should butt up (0 gap)
Background rhythm	Page has visual rhythm — some variation in section backgrounds (alternating light/dark, or strategic use of color). Flag a page where every section is the same plain background
Composition purity — single file	Design system layout directories (src/pages/design-system/layouts/) must contain only one .astro file. Flag extra files
Composition purity — zero classes	In layouts and site pages, no Tailwind utility classes on raw HTML elements. Only section-flow on <main> is allowed. If a <div> needs a class, a component is missing
Composition purity — no client code	Flag inline <script> tags in layouts and site pages. Use Preact islands via components instead
Composition drift	When auditing a layout that has a corresponding site page (or vice versa), check for structural divergence — different section order, missing/extra sections, different component usage. Copy differences are expected (placeholder vs real content). Structural differences are a bug
SEO	Site pages (not layouts) have <title>, <meta name="description">. Template-driven pages wire SEO from table fields (meta_title, meta_description). Flag missing OG tags on public-facing pages

Soft Rules

• Anti-pattern violations — anything listed in system.md Anti-Patterns section.
• Pattern consistency — does this component follow the conventions established by existing components? Read 2–3 peers to compare.
• Personality alignment (swap test) — could you swap this component's styling for the most generic version and the design wouldn't feel different? If yes, it's defaulting — flag it.
• Prose utility — prose is applied at the <main> level as an ambient typography baseline. Its descendant selectors use :where() for low specificity, so any Tailwind class on a component naturally overrides it. The only local prose usage is for nested content zones that need their own vertical rhythm. Components (cards, heroes) should NOT use prose — they own their spacing explicitly via gap-* classes.
• Finishing touches — are there opportunities to supercharge defaults? Custom list bullets, styled blockquotes, accent borders, subtle background decoration. Don't mandate these, but suggest where they'd elevate the work.

Output

Report all violations with: file path, line number, rule category, rule name, and suggested fix.

Severity levels:

• Error — hard rule violation. Must fix.
• Warning — design rule violation. Should fix — explain why.
• Info — soft rule suggestion. Propose, don't mandate.

Group findings by file, then by severity. Fix all errors and warnings before showing components to the user.