@jaimevalasek/aioson 1.3.0 → 1.4.0

package/template/.aioson/skills/design/cognitive-core-ui/references/websites.md

@@ -0,0 +1,350 @@
+# Websites & Landing Pages — Cognitive Core UI
+
+Read after `design-tokens.md` and `components.md`. When building websites, leave `dashboards.md` out of context.
+
+The Cognitive Core visual identity scales from dashboards to websites. Same typography, token system, and component vocabulary — but with more whitespace, hero typography, and narrative hierarchy.
+
+A commercial page using this skill should feel **premium and technical, but still behave like a website.** It cannot look like an admin dashboard with the word "site" pasted on top.
+
+## Website Stance
+
+**Use these traits:**
+- Stronger narrative hierarchy — one message per section
+- More whitespace between sections (`--space-16` to `--space-24`)
+- Fewer panels above the fold — never five cards competing with the main message
+- Larger display headings (`--text-5xl` for hero)
+- Mono labels only as supporting spice, not the main reading experience
+- One strong accent family carried through the whole page
+
+**Avoid these traits:**
+- Persistent sidebars on marketing pages
+- Operational rails and dense status grids above the fold
+- Dashboard feeds unless the brand explicitly needs that look
+- Five equal-weight cards before the value proposition
+- Cyan glow overuse — websites need calm areas
+- Uppercase mono for entire paragraphs, nav groups, or section copy
+- Every section bordered like a dashboard card
+
+## Website Anti-Patterns
+
+1. Do not use a dashboard shell for a landing page — no persistent sidebar, no live-feed panel.
+2. Do not place stat cards before the main value proposition unless the proof IS the product.
+3. Do not overuse cyan/teal glow. Websites need breathing room.
+4. Do not make every section a bordered card — alternate backgrounds instead.
+5. Do not use a hero that is just a grid of equal-weight feature cards. The hero must have ONE dominant message.
+
+---
+
+## Default theme for websites
+
+- **Light theme**: Institutional sites, corporate, marketing pages, client-facing products
+- **Dark theme**: Tech products, SaaS, developer tools, agencies
+- **Both with toggle**: When the user asks, or when the site needs broad appeal
+
+If the user does not specify, use **dark with a light option toggle** for tech/SaaS, or **light with a dark option toggle** for institutional/corporate.
+
+---
+
+## 1. Landing Page
+
+```
+┌────────────────────────────────────────────────────────┐
+│  TOP BAR (sticky, bg-void on scroll, transparent hero) │
+├────────────────────────────────────────────────────────┤
+│                                                         │
+│  HERO SECTION (padding: space-24 top, space-20 bottom) │
+│  ┌──────────────────────────────────────────────────┐  │
+│  │ MONO LABEL: tagline (centered)                   │  │
+│  │ DISPLAY HEADING text-5xl, weight-black (centered)│  │
+│  │ Subtitle: text-lg, text-secondary (centered)     │  │
+│  │ [CTA Primary Button]  [Secondary Button]         │  │
+│  └──────────────────────────────────────────────────┘  │
+│                                                         │
+├────────────────────────────────────────────────────────┤
+│  FEATURES (bg-surface, padding: space-20)              │
+│  Section Header (centered: mono label + display title) │
+│  Card Grid: [InfoCard] [InfoCard] [InfoCard]  3-col    │
+│                                                         │
+├────────────────────────────────────────────────────────┤
+│  STATS (bg-base, padding: space-16)                    │
+│  [StatCard] [StatCard] [StatCard] [StatCard]           │
+│                                                         │
+├────────────────────────────────────────────────────────┤
+│  SOCIAL PROOF (bg-surface, padding: space-16)          │
+│  Quote cards in 2-col grid or testimonial strip        │
+│                                                         │
+├────────────────────────────────────────────────────────┤
+│  CTA SECTION (bg-void, accent radial glow, space-20)   │
+│  Display heading + mono label + CTA Button (centered)  │
+│                                                         │
+├────────────────────────────────────────────────────────┤
+│  FOOTER (bg-void, border-top: border-subtle)           │
+│  [Brand | Links | Links | Newsletter or Social]        │
+└────────────────────────────────────────────────────────┘
+```
+
+### Hero section (required elements)
+
+1. **Mono label** above heading — category / tagline in monospace uppercase
+2. **Display heading** — `text-5xl`, `weight-black`, `tracking-tight`, `line-height: 1.1`
+3. **Subtitle** — 1–2 sentences, `text-lg`, `text-secondary`
+4. **Two CTAs** — primary (solid accent) + secondary (outline or ghost)
+5. **Optional**: hero visual (screenshot, illustration, or abstract mesh)
+
+```css
+.hero {
+  min-height: 90vh; display: flex; align-items: center; justify-content: center;
+  padding: var(--space-24) var(--space-6) var(--space-20);
+  text-align: center;
+  background: var(--bg-base);
+  position: relative; overflow: hidden;
+}
+.hero-content { max-width: 760px; position: relative; z-index: 1; }
+.hero-mono-label {
+  font-family: var(--font-mono); font-size: var(--text-xs);
+  color: var(--accent); letter-spacing: var(--tracking-widest);
+  text-transform: uppercase; margin-bottom: var(--space-4);
+  display: inline-flex; align-items: center; gap: var(--space-2);
+}
+.hero-heading {
+  font-family: var(--font-display); font-size: var(--text-5xl);
+  font-weight: var(--weight-black); color: var(--text-heading);
+  letter-spacing: var(--tracking-tight); line-height: 1.05;
+  margin-bottom: var(--space-5);
+}
+.hero-subtitle {
+  font-size: var(--text-lg); color: var(--text-secondary);
+  line-height: var(--leading-relaxed); margin-bottom: var(--space-8);
+  max-width: 560px; margin-left: auto; margin-right: auto;
+}
+.hero-actions { display: flex; gap: var(--space-3); justify-content: center; flex-wrap: wrap; }
+```
+
+**Optional hero glow (dark theme):**
+```css
+.hero::before {
+  content: ''; position: absolute; inset: 0;
+  background: radial-gradient(ellipse 800px 600px at 50% 30%, var(--accent-glow), transparent 70%);
+  pointer-events: none;
+}
+```
+
+### Section max-width container
+
+```css
+.container { max-width: 1200px; margin: 0 auto; padding: 0 var(--space-6); }
+.section { padding: var(--space-20) var(--space-6); }
+.section-header { text-align: center; margin-bottom: var(--space-10); }
+.section-mono-label {
+  font-family: var(--font-mono); font-size: var(--text-xs);
+  color: var(--accent); letter-spacing: var(--tracking-widest);
+  text-transform: uppercase; margin-bottom: var(--space-3);
+}
+.section-heading {
+  font-family: var(--font-display); font-size: var(--text-3xl);
+  font-weight: var(--weight-black); color: var(--text-heading);
+  letter-spacing: var(--tracking-tight); line-height: var(--leading-tight);
+}
+```
+
+### Features / Benefits section
+
+Use Info Cards (from `components.md`) in a 3-column grid:
+
+```css
+.features-grid {
+  display: grid; gap: var(--space-5);
+  grid-template-columns: repeat(3, 1fr);
+}
+@media (max-width: 900px) { .features-grid { grid-template-columns: 1fr; } }
+```
+
+Each card: icon + mono label + heading + description paragraph. Use `var(--bg-elevated)` as card background for contrast against the section.
+
+### Stats section
+
+Row of 4 stat cards. Use light background (`bg-surface`) for the stat numbers section:
+
+```css
+.stats-section { background: var(--bg-surface); }
+.stats-row { display: flex; gap: var(--space-5); flex-wrap: wrap; justify-content: center; }
+.stats-row .stat-card { flex: 1; min-width: 180px; text-align: center; }
+```
+
+Stat card center-aligned variant:
+- Mono label centered
+- Large number centered, accent color optional
+- Short subtitle below
+
+### Social proof / Testimonials
+
+```css
+.testimonials-grid { display: grid; grid-template-columns: repeat(2, 1fr); gap: var(--space-5); }
+@media (max-width: 768px) { .testimonials-grid { grid-template-columns: 1fr; } }
+```
+
+Testimonial card:
+```css
+.testimonial-card {
+  background: var(--bg-surface); border: 1px solid var(--border-subtle);
+  border-radius: var(--radius-lg); padding: var(--space-6);
+}
+.testimonial-quote {
+  font-size: var(--text-base); color: var(--text-primary);
+  line-height: var(--leading-relaxed); font-style: italic;
+  margin-bottom: var(--space-4);
+}
+.testimonial-author {
+  font-family: var(--font-mono); font-size: var(--text-xs);
+  color: var(--text-muted); letter-spacing: var(--tracking-wider); text-transform: uppercase;
+}
+```
+
+### CTA section
+
+```css
+.cta-section {
+  background: var(--bg-void); text-align: center;
+  position: relative; overflow: hidden;
+}
+.cta-section::before {
+  content: ''; position: absolute; inset: 0;
+  background: radial-gradient(ellipse 600px 400px at 50% 50%, var(--accent-glow), transparent);
+  pointer-events: none;
+}
+.cta-content { position: relative; z-index: 1; max-width: 640px; margin: 0 auto; }
+```
+
+### Top navigation (landing pages)
+
+Same structure as dashboard top bar, with these differences:
+- Initially transparent background, transitions to `bg-void` on scroll
+- Links are page anchor links (`#features`, `#pricing`, `#about`)
+- Add `data-scrolled` attribute via JS to trigger background fill
+
+```css
+.topbar { transition: background var(--transition-slow), border-color var(--transition-slow); }
+.topbar[data-scrolled="true"] {
+  background: var(--bg-void);
+  border-bottom: 1px solid var(--border-subtle);
+  backdrop-filter: blur(12px);
+}
+```
+
+---
+
+## 2. Institutional / Corporate Site
+
+Same as landing page with these additions:
+
+### About page
+```
+Hero (short, 50vh) → Text block + values card grid → Team card grid → CTA
+```
+
+### Team card
+```css
+.team-card { text-align: center; background: var(--bg-surface); border: 1px solid var(--border-subtle); border-radius: var(--radius-lg); padding: var(--space-6); }
+.team-avatar { width: 80px; height: 80px; border-radius: 50%; border: 2px solid var(--border-subtle); margin: 0 auto var(--space-4); object-fit: cover; }
+.team-name { font-weight: var(--weight-bold); color: var(--text-heading); }
+.team-role { color: var(--accent); font-style: italic; font-size: var(--text-sm); }
+.team-bio { font-size: var(--text-sm); color: var(--text-secondary); margin-top: var(--space-2); line-height: var(--leading-relaxed); }
+```
+
+### Services page
+```
+Hero → Service cards grid (3-col) → Why Us stats row → CTA
+```
+
+### Contact page
+```
+Two columns: [Left: contact info cards] [Right: form card]
+```
+
+---
+
+## 3. Footer
+
+```css
+.footer {
+  background: var(--bg-void); border-top: 1px solid var(--border-subtle);
+  padding: var(--space-10) var(--space-6) var(--space-6);
+}
+.footer-grid {
+  display: grid; grid-template-columns: 2fr 1fr 1fr 1fr;
+  gap: var(--space-8); margin-bottom: var(--space-8);
+}
+.footer-brand { /* brand column */ }
+.footer-col-label {
+  font-family: var(--font-mono); font-size: var(--text-xs);
+  color: var(--text-muted); letter-spacing: var(--tracking-widest);
+  text-transform: uppercase; margin-bottom: var(--space-4);
+}
+.footer-link {
+  display: block; color: var(--text-secondary); text-decoration: none;
+  font-size: var(--text-sm); margin-bottom: var(--space-2);
+  transition: color var(--transition-fast);
+}
+.footer-link:hover { color: var(--accent); }
+.footer-bottom {
+  border-top: 1px solid var(--border-subtle); padding-top: var(--space-4);
+  display: flex; justify-content: space-between; align-items: center;
+  font-size: var(--text-sm); color: var(--text-muted);
+}
+@media (max-width: 768px) {
+  .footer-grid { grid-template-columns: 1fr 1fr; gap: var(--space-6); }
+}
+```
+
+---
+
+## 4. Buttons (website variants)
+
+Primary CTA button:
+```css
+.btn-primary {
+  background: var(--accent); color: var(--bg-base);
+  font-family: var(--font-mono); font-size: var(--text-sm);
+  font-weight: var(--weight-semibold); letter-spacing: var(--tracking-wide);
+  text-transform: uppercase; padding: var(--space-3) var(--space-6);
+  border-radius: var(--radius-md); border: none; cursor: pointer;
+  transition: var(--transition-base);
+  box-shadow: 0 0 20px var(--accent-glow);
+}
+.btn-primary:hover {
+  background: var(--accent-hover);
+  box-shadow: 0 0 32px var(--accent-glow), 0 4px 12px rgba(0,0,0,0.2);
+  transform: translateY(-1px);
+}
+```
+
+Secondary button:
+```css
+.btn-secondary {
+  background: transparent; color: var(--text-primary);
+  border: 1px solid var(--border-medium);
+  font-family: var(--font-mono); font-size: var(--text-sm);
+  font-weight: var(--weight-semibold); letter-spacing: var(--tracking-wide);
+  text-transform: uppercase; padding: var(--space-3) var(--space-6);
+  border-radius: var(--radius-md); cursor: pointer;
+  transition: var(--transition-base);
+}
+.btn-secondary:hover {
+  border-color: var(--border-accent);
+  color: var(--accent);
+}
+```
+
+---
+
+## Key differences: dashboard vs website
+
+| Aspect | Dashboard | Website |
+|---|---|---|
+| Default theme | Dark | Light (or dark for tech) |
+| Section padding | `space-4 to space-5` | `space-16 to space-24` |
+| Content max-width | Full layout with sidebar | `1200px` centered |
+| Heading size | `text-2xl` max | `text-5xl` for hero |
+| Cards | Dense, compact | Spacious, feature-oriented |
+| Navigation | Tab-heavy, sidebar | Linear anchors, single bar |
+| Background alternation | Same bg-base | Alternates `bg-base` / `bg-surface` |

package/template/.aioson/skills/design/interface-design/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: interface-design
+description: Interface Design is a craft-first packaged design skill for choosing an intentional visual direction, building a stable token system, and maintaining UI continuity across screens. Use it when `design_skill: interface-design` is selected or when the user explicitly chooses this broad craft package.
+---
+
+# Interface Design
+
+This is a general design-craft package.
+It helps the agent make strong decisions when the user wants a deliberate, high-quality UI but has not chosen a niche visual language such as `cognitive-ui` or `premium-command-center-ui`.
+
+## Package structure
+
+```text
+.aioson/skills/design/interface-design/
+  SKILL.md
+  references/
+    intent-and-domain.md
+    design-directions.md
+    tokens-and-depth.md
+    components-and-states.md
+    handoff-and-quality.md
+```
+
+## Activation rules
+
+- Apply this package only when `design_skill: interface-design` is selected.
+- Do not combine it with any other design skill.
+- Use it when the user wants strong design craft but has not asked for a very specific visual system.
+
+## Loading guide
+
+| Task | Load |
+|---|---|
+| Any visual work | `references/intent-and-domain.md` + `references/design-directions.md` |
+| Tokens and system decisions | add `references/tokens-and-depth.md` |
+| Component behavior | add `references/components-and-states.md` |
+| Final delivery quality | add `references/handoff-and-quality.md` |
+
+## Positioning
+
+Use this package for:
+- general web apps
+- websites that need strong craft but not a preset style language
+- redesigns that need a clearer system
+- multi-screen work where continuity matters
+
+Do not use it when a more explicit visual package was selected.

package/template/.aioson/skills/design/interface-design/references/components-and-states.md

@@ -0,0 +1,105 @@
+# Components and States — Interface Design
+
+---
+
+## Component quality (mandatory for every component)
+
+Define all six states before handing off to @dev:
+
+| State | What to specify |
+|---|---|
+| Default | Baseline appearance |
+| Hover | Subtle shift (background, border, or opacity) |
+| Focus | Visible ring — `outline: 2px solid brand/primary; outline-offset: 2px` |
+| Active / pressed | Slight scale or brightness change |
+| Disabled | Reduced opacity (0.4–0.5), no cursor pointer, no hover effect |
+| Loading | Skeleton or spinner — never block critical flow |
+
+Container components also need:
+- **Empty state** — illustration or message + primary action
+- **Error state** — clear message + recovery action
+- **Success confirmation** — when relevant, transient (not permanent)
+
+---
+
+## Forms
+
+- Labels outside placeholders. Placeholders are hints, not labels.
+- Validate on blur (not on keystroke, not on submit only).
+- Inline field errors directly below the field. One global summary for multi-field failures.
+- Disable the submit button and show progress during async operations.
+- Input height minimum: 40px (desktop), 44px (mobile/touch) — **consumer/public-facing forms only.**
+
+**Admin / operational form scale (settings, config, entity managers):**
+
+```
+Label  : text-[0.65rem]  mb: 2px          ← not text-sm mb-2
+Input  : px-3 py-2  text-xs  radius 10–12px  (height ~32px)
+Select : px-3 py-2  text-xs  radius 10–12px
+Button : px-3 py-2  text-xs  radius 10–12px
+```
+
+The 40px minimum only applies to authenticated public flows (login, onboarding, checkout). In dense admin contexts, 32px controls reduce visual weight without usability loss — the audience is power users, not first-time visitors.
+
+**Entity add/edit forms → Modal, not inline expansion:**
+- Inline accordions (RevealPanel, details-based expansion) inside entity cards cause layout shift and make the page feel unstable
+- Correct pattern: `+ Add` button + `Edit` button each open a centered modal (`max-w-448px`, `backdrop-blur overlay`)
+- Modal form: single-column, `gap: 10px`, compact controls, full-width submit button
+
+---
+
+## Typography hierarchy
+
+Size alone is never enough. Use weight + tracking + opacity to create layers:
+
+```
+Page title    : largest size, 600-weight, tight tracking
+Section title : medium-large, 500-weight, normal tracking
+Body          : base size, 400-weight, comfortable line-height (1.5–1.6)
+Helper / meta : small, 400-weight, muted color
+Data / mono   : monospace for numbers in tables, code, metrics
+```
+
+---
+
+## Layout and composition
+
+- **Rhythm** — interfaces breathe unevenly: dense tool areas give way to open content. Same card size, same gaps everywhere = flatness = no one decided.
+- **Proportions declare intent** — a 280px sidebar says "navigation serves content." A 360px sidebar says "these are peers." Know what your proportions are saying.
+- **One focal point per screen** — the primary action dominates through size, position, contrast, or surrounding space. When everything competes equally, nothing wins.
+- **Reading order** — 1. Page intent → 2. Primary action → 3. Supporting data. Never invert.
+
+---
+
+## Accessibility baseline (non-negotiable)
+
+- Semantic HTML and proper landmarks (`<main>`, `<nav>`, `<header>`, `<aside>`)
+- Full keyboard navigation — Tab order must match visual reading order
+- Visible focus rings on all interactive elements
+- Color contrast: 4.5:1 for body text, 3:1 for large text and UI components
+- Never convey meaning through color alone — add icon, pattern, or text
+- `aria-label` on icon-only buttons, `aria-live` on dynamic status regions
+- `prefers-reduced-motion` fallback for all animations
+
+---
+
+## Motion rules
+
+- Motion clarifies transitions, it does not decorate them.
+- Duration: micro-interactions 100–150ms, page transitions 200–300ms.
+- Easing: ease-out for entrances, ease-in for exits.
+- Never animate properties that affect layout (width, height, padding). Animate transform and opacity only.
+- Always provide `prefers-reduced-motion: reduce` fallback.
+
+---
+
+## Stack-specific notes
+
+| Stack | Priority |
+|---|---|
+| Laravel + TALL | Flux UI / Livewire primitives first; custom only for signature moves |
+| Filament | Built-in Filament components before any override |
+| Next.js + shadcn/ui | shadcn primitives + Tailwind tokens; keep component boundaries clean |
+| React + Tailwind | Design token CSS vars → Tailwind config → components |
+| Vue + Nuxt | Nuxt UI or PrimeVue first; avoid mixing component libraries |
+| Vanilla HTML | Define CSS custom properties at `:root`, semantic class names only |

package/template/.aioson/skills/design/interface-design/references/design-directions.md

@@ -0,0 +1,101 @@
+# Design Directions — Interface Design
+
+Choose ONE direction. Never mix. Mixing produces visual noise.
+The chosen direction defines spacing, typography, border strategy, depth, and motion posture — before components are built.
+
+---
+
+## Precision & Density
+
+*For: dashboards, admin panels, developer tools, power-user interfaces.*
+
+```
+Foundation : Cool slate (borders-only depth)
+Spacing    : 4px base — scale: 4, 8, 12, 16, 24, 32
+Colors     : foreground=slate-900, secondary=slate-600, muted=slate-400,
+             faint=slate-200, border=rgba(0,0,0,0.08), accent=blue-600
+Radius     : 4px / 6px / 8px  (sharp, technical)
+Typography : system-ui, 11–18px, weights 400/500/600
+             monospace: SF Mono, Consolas (for data/code)
+Components :
+  Button   → 32px height, 8px/12px padding, 4px radius, 13px 500-weight
+  Card     → 0.5px faint border, 12px padding, 6px radius, NO shadows
+  Table    → 8px/12px cell padding, tabular-nums, 13px font, 1px bottom border
+Rationale  : borders-only maximizes density; compact sizing serves power users;
+             system fonts feel native and load instantly.
+```
+
+---
+
+## Warmth & Approachability
+
+*For: consumer apps, collaborative tools, onboarding flows, customer-facing products.*
+
+```
+Foundation : Warm stone (subtle shadows)
+Spacing    : 4px base — scale: 8, 12, 16, 24, 32, 48 (generous)
+Colors     : foreground=stone-900, secondary=stone-600, accent=orange-500,
+             surface=white on stone-50
+Radius     : 8px / 12px / 16px  (rounded, friendly)
+Typography : Inter, 13–24px, weights 400/500/600
+Components :
+  Button   → 40px height, 12px/20px padding, 8px radius
+  Card     → 20px padding, 12px radius, white on stone-50
+  Input    → 44px height, 12px/16px padding, 1.5px faint border
+Rationale  : subtle shadows add approachable depth; generous spacing enables
+             focused tasks; warm tones feel human and inviting.
+```
+
+---
+
+## Sophistication & Trust
+
+*For: fintech, enterprise SaaS, operational products where clarity and trust matter more than novelty.*
+
+```
+Foundation : Cool mineral (restrained layers)
+Spacing    : 4px base — scale: 4, 8, 12, 16, 24, 32
+Colors     : foreground=slate-950, secondary=slate-700, muted=slate-500,
+             surface=white, border=rgba(15,23,42,0.10), accent=blue-700
+Radius     : 8px / 10px / 12px  (firm, not playful)
+Typography : IBM Plex Sans or Public Sans, 12–20px, weights 400/500/600
+Components :
+  Button   → 38px height, 12px/18px padding, 10px radius
+  Card     → 16px padding, 10px radius, subtle border, rare soft shadow
+  Table    → 10px/14px cell padding, tabular-nums, quiet row dividers
+Rationale  : trust comes from control, not decoration; a restrained palette and
+             firm typography make the product feel expensive and dependable.
+```
+
+---
+
+## Premium Dark Platform
+
+*For: premium dashboards, media/catalog products, command surfaces, high-density apps with persistent navigation.*
+
+```
+Foundation : Graphite layers (borders-first)
+Spacing    : 4px base — scale: 4, 8, 12, 16, 24, 32
+Colors     : base=#0b1015, surface=#10161d, elevated=#151c24,
+             foreground=#f3f7fb, secondary=#b7c2cf, muted=#7f8b99,
+             border=rgba(255,255,255,0.08), accent=desaturated blue
+Radius     : 12px / 14px / 16px  (premium, controlled)
+Typography : Manrope, Geist, or IBM Plex Sans, 12–22px, weights 400/500/600
+Components :
+  Button   → 40px height, 12px/18px padding, 12px radius
+  Card     → layered surfaces, 16px padding, 14px radius, no heavy glow
+  Sidebar  → quiet active state, compact icon rhythm, clean section grouping
+Rationale  : premium dark works when contrast is controlled, surfaces are few,
+             and borders quietly separate the system without turning neon.
+```
+
+---
+
+## Other directions (adapt token specs above)
+
+- **Data & Analysis** — cool blue, high-density tables, monospace for numbers, minimal chrome
+- **Editorial** — strong typographic hierarchy, generous white space, restrained color
+- **Commerce** — aspirational photography support, high contrast CTAs, smooth transitions
+- **Minimal & Calm** — near-monochrome, whitespace as design element, hairline borders only
+- **Boldness & Clarity** — stronger accent, harder contrast, one dominant focal move
+- **Utility & Function** — minimal decoration, maximum legibility, near-invisible chrome

package/template/.aioson/skills/design/interface-design/references/handoff-and-quality.md

@@ -0,0 +1,71 @@
+# Handoff and Quality — Interface Design
+
+---
+
+## Quality checks (run before delivering)
+
+### Swap test
+Would swapping the typeface or layout make the design look like a different product?
+If yes — good. If no — the design has no identity.
+
+### Squint test
+Blur your eyes (or the screenshot). Does the visual hierarchy still read clearly?
+If not — the hierarchy is too weak.
+
+### Signature test
+Can you point to five specific decisions where your craft appears?
+If you cannot name five — you defaulted somewhere.
+
+### Token test
+Do your CSS variable names sound like they belong to THIS product?
+Generic: `--color-primary`. Specific: `--slot-available`, `--urgency-amber`.
+
+---
+
+## Self-critique before delivery
+
+Walk through each section before handing off:
+
+1. **Composition** — Does the layout have rhythm? Are proportions intentional? Is there one clear focal point?
+2. **Craft** — Is every spacing value on-grid? Does typography use weight + tracking + size (not size alone)? Do surfaces whisper hierarchy without thick borders or dramatic shadows?
+3. **Content** — Does the spec tell one coherent story? Could a real person at a real company act on this?
+4. **Structure** — Are there any hacks? Negative-margin workarounds? Arbitrary pixel values? Fix them.
+
+**Ask yourself: "If a design lead reviewed this, what would they call out?" Fix that thing. Then ask again.**
+
+---
+
+## Handoff to @dev
+
+A strong handoff includes:
+- Explicit visual direction and anti-goals
+- Design token block (fonts, colors, spacing, radius, depth strategy, motion posture)
+- Per-screen layout notes with component names mapped to real library components
+- Full state matrix (default / hover / focus / active / disabled / loading / empty / error / success)
+- Responsive rules (mobile breakpoints, collapse behavior)
+- Accessibility checklist items
+- Any signature visual moves with implementation notes
+- Anti-patterns to avoid
+
+The `ui-spec.md` must be concise enough to code from directly. Not a design document — a build contract.
+
+---
+
+## Update design memory
+
+When the work introduces or changes reusable design decisions, update `.interface-design/system.md` with:
+- Final direction and anti-goals
+- Token block
+- Component pattern notes
+- New exceptions or constraints
+
+This file is the continuity layer between screens, agents, and future sessions.
+
+---
+
+## Quality bar
+
+1. The result must not look generic.
+2. Repeated elements must share spacing, radius, and depth logic.
+3. Typography hierarchy must be legible without decorative tricks.
+4. The screen must communicate purpose before style.