aragrp/docs/design-system/quality-checklist.md

Quality Checklist

Run this checklist before finishing any UI task or opening a PR that touches presentation.

Layout

• ✓ Container consistency — uses <Container> / layout.container
• ✓ Grid consistency — grids sit inside the container; gaps from the spacing scale
• ✓ Section rhythm — layout.sectionY (or documented hero top padding)
• ✓ Alignment — matches header/footer edges
• ✓ No overflow — no accidental horizontal scroll; decor clipped

Tokens

• ✓ Same spacing scale — no arbitrary px-[N] / gap-[N]
• ✓ Same typography — type.* / <Typography>
• ✓ Semantic colors only — no hardcoded hex
• ✓ Same radius — --radius scale / rounded-blog where intended
• ✓ Same shadows — shadow-xs/sm/md or shadow-glow-primary

Components

• ✓ Same button system — @/components/ui/button
• ✓ Same cards — @/components/ui/card (when a card is warranted)
• ✓ No duplicated primitives — no second Button/Card/Input
• ✓ Forms use shared Input/Field/Label patterns

Interaction

• ✓ Same hover behavior — matches neighboring components
• ✓ Same transition timing — 200ms UI / 300ms chrome / 500ms reveals
• ✓ Transform/opacity for motion — no layout animation abuse
• ✓ Reduced motion honored

Theme & responsive

• ✓ Same dark mode — verified with theme toggle
• ✓ Responsive — mobile / tablet / desktop checked
• ✓ Touch targets adequate

Accessibility

• ✓ Focus rings visible
• ✓ Keyboard operable
• ✓ Icon buttons labeled
• ✓ Contrast acceptable in light and dark
• ✓ Images have correct alt / decorative handling

Stability

• ✓ No layout shift — images sized; fonts not causing CLS spikes
• ✓ No duplicated styles — no copy-pasted one-off CSS competing with tokens
• ✓ Imported Shadcn/Tailark blocks fully adapted (shadcn.md)

Final gate

If any item fails, fix before merge. When unsure, re-read README.md priority order:

1. Accessibility
2. Layout & container
3. Semantic tokens
4. Component systems
5. Visual effects
6. Imported blocks