maestro-flow 0.5.36 → 0.5.37

package/.agents/skills/team-uidesign/specs/pipelines.md

@@ -1,76 +1,76 @@
-# Pipeline Definitions
-
-UI design pipeline modes and task registry.
-
-## Pipeline Modes
-
-| Mode | Description | Task Count |
-|------|-------------|------------|
-| component | Single component: research -> design -> audit -> build | 4 tasks |
-| system | Design system: dual-track with 2 sync points | 7 tasks |
-| full-system | Full design system + final integrated audit | 8 tasks |
-
-## Component Pipeline Task Registry
-
-| Task ID | Role | blockedBy | Description |
-|---------|------|-----------|-------------|
-| RESEARCH-001 | researcher | [] | Design system analysis, component inventory, accessibility baseline |
-| DESIGN-001 | designer | [RESEARCH-001] | Design tokens + component spec with all 5 interactive states |
-| AUDIT-001 | reviewer | [DESIGN-001] | 5-dimension audit: consistency, accessibility, completeness, quality, compliance |
-| BUILD-001 | implementer | [AUDIT-001] | CSS custom properties + component code + ARIA + keyboard navigation |
-
-## System Pipeline Task Registry
-
-| Task ID | Role | blockedBy | Description |
-|---------|------|-----------|-------------|
-| RESEARCH-001 | researcher | [] | Design system analysis across all components |
-| DESIGN-001 | designer | [RESEARCH-001] | Token system design |
-| AUDIT-001 | reviewer | [DESIGN-001] | Token audit [Sync Point 1: QUALITY-001] |
-| DESIGN-002 | designer | [AUDIT-001] | Component specification (parallel) |
-| BUILD-001 | implementer | [AUDIT-001] | Token code implementation (parallel) |
-| AUDIT-002 | reviewer | [DESIGN-002] | Component audit [Sync Point 2] |
-| BUILD-002 | implementer | [AUDIT-002, BUILD-001] | Component code implementation |
-
-## Full-System Pipeline Task Registry
-
-Same as System pipeline, plus:
-
-| Task ID | Role | blockedBy | Description |
-|---------|------|-----------|-------------|
-| AUDIT-003 | reviewer | [BUILD-002] | Final integrated audit (cross-cutting) |
-
-## Checkpoints / Sync Points
-
-| Checkpoint | Task | Condition | Action |
-|------------|------|-----------|--------|
-| QUALITY-001: Sync Point 1 | AUDIT-001 completes | Score >= 8, critical == 0 | Unblock DESIGN-002 + BUILD-001 (parallel) |
-| QUALITY-001: GC Loop | AUDIT-* completes | Score < 8 or critical > 0 | Create DESIGN-fix task, new AUDIT task (max 2 rounds) |
-
-## GC Loop Behavior
-
-| Signal | Condition | Action |
-|--------|-----------|--------|
-| audit_passed | Score >= 8, critical == 0 | GC converged -> record sync_point -> unblock downstream |
-| audit_result | Score 6-7, no critical | gc_rounds < max -> create DESIGN-fix task |
-| fix_required | Score < 6 or critical > 0 | gc_rounds < max -> create DESIGN-fix task (CRITICAL) |
-| Any | gc_rounds >= max | Escalate to user: accept / try one more / terminate |
-
-## Parallel Spawn Rules
-
-| Mode | After | Spawn Behavior |
-|------|-------|----------------|
-| component | Sequential | One task at a time |
-| system | Sync Point 1 (AUDIT-001) | Spawn DESIGN-002 + BUILD-001 in parallel |
-| system | AUDIT-002 | Spawn BUILD-002 |
-| full-system | Sync Point 1 (AUDIT-001) | Spawn DESIGN-002 + BUILD-001 in parallel |
-| full-system | BUILD-002 | Spawn AUDIT-003 |
-
-## Output Artifacts
-
-| Task | Output Path |
-|------|-------------|
-| RESEARCH-001 | <session>/research/*.json |
-| DESIGN-001 | <session>/design/design-tokens.json + component-specs/*.md |
-| AUDIT-* | <session>/audit/audit-<NNN>.md |
-| BUILD-001 | <session>/build/token-files/* |
-| BUILD-002 | <session>/build/component-files/* |
+# Pipeline Definitions
+
+UI design pipeline modes and task registry.
+
+## Pipeline Modes
+
+| Mode | Description | Task Count |
+|------|-------------|------------|
+| component | Single component: research -> design -> audit -> build | 4 tasks |
+| system | Design system: dual-track with 2 sync points | 7 tasks |
+| full-system | Full design system + final integrated audit | 8 tasks |
+
+## Component Pipeline Task Registry
+
+| Task ID | Role | blockedBy | Description |
+|---------|------|-----------|-------------|
+| RESEARCH-001 | researcher | [] | Design system analysis, component inventory, accessibility baseline |
+| DESIGN-001 | designer | [RESEARCH-001] | Design tokens + component spec with all 5 interactive states |
+| AUDIT-001 | reviewer | [DESIGN-001] | 5-dimension audit: consistency, accessibility, completeness, quality, compliance |
+| BUILD-001 | implementer | [AUDIT-001] | CSS custom properties + component code + ARIA + keyboard navigation |
+
+## System Pipeline Task Registry
+
+| Task ID | Role | blockedBy | Description |
+|---------|------|-----------|-------------|
+| RESEARCH-001 | researcher | [] | Design system analysis across all components |
+| DESIGN-001 | designer | [RESEARCH-001] | Token system design |
+| AUDIT-001 | reviewer | [DESIGN-001] | Token audit [Sync Point 1: QUALITY-001] |
+| DESIGN-002 | designer | [AUDIT-001] | Component specification (parallel) |
+| BUILD-001 | implementer | [AUDIT-001] | Token code implementation (parallel) |
+| AUDIT-002 | reviewer | [DESIGN-002] | Component audit [Sync Point 2] |
+| BUILD-002 | implementer | [AUDIT-002, BUILD-001] | Component code implementation |
+
+## Full-System Pipeline Task Registry
+
+Same as System pipeline, plus:
+
+| Task ID | Role | blockedBy | Description |
+|---------|------|-----------|-------------|
+| AUDIT-003 | reviewer | [BUILD-002] | Final integrated audit (cross-cutting) |
+
+## Checkpoints / Sync Points
+
+| Checkpoint | Task | Condition | Action |
+|------------|------|-----------|--------|
+| QUALITY-001: Sync Point 1 | AUDIT-001 completes | Score >= 8, critical == 0 | Unblock DESIGN-002 + BUILD-001 (parallel) |
+| QUALITY-001: GC Loop | AUDIT-* completes | Score < 8 or critical > 0 | Create DESIGN-fix task, new AUDIT task (max 2 rounds) |
+
+## GC Loop Behavior
+
+| Signal | Condition | Action |
+|--------|-----------|--------|
+| audit_passed | Score >= 8, critical == 0 | GC converged -> record sync_point -> unblock downstream |
+| audit_result | Score 6-7, no critical | gc_rounds < max -> create DESIGN-fix task |
+| fix_required | Score < 6 or critical > 0 | gc_rounds < max -> create DESIGN-fix task (CRITICAL) |
+| Any | gc_rounds >= max | Escalate to user: accept / try one more / terminate |
+
+## Parallel Spawn Rules
+
+| Mode | After | Spawn Behavior |
+|------|-------|----------------|
+| component | Sequential | One task at a time |
+| system | Sync Point 1 (AUDIT-001) | Spawn DESIGN-002 + BUILD-001 in parallel |
+| system | AUDIT-002 | Spawn BUILD-002 |
+| full-system | Sync Point 1 (AUDIT-001) | Spawn DESIGN-002 + BUILD-001 in parallel |
+| full-system | BUILD-002 | Spawn AUDIT-003 |
+
+## Output Artifacts
+
+| Task | Output Path |
+|------|-------------|
+| RESEARCH-001 | <session>/research/*.json |
+| DESIGN-001 | <session>/design/design-tokens.json + component-specs/*.md |
+| AUDIT-* | <session>/audit/audit-<NNN>.md |
+| BUILD-001 | <session>/build/token-files/* |
+| BUILD-002 | <session>/build/component-files/* |

package/.agents/skills/team-uidesign/specs/scoring-guide.md

@@ -1,114 +1,114 @@
-# 8-Dimension Quality Scoring Rubric
-
-Score each dimension 0-4. Total: 0-32.
-
-## Dimensions
-
-### 1. Anti-AI-Slop (Weight: 10%)
-
-| Score | Criteria |
-|-------|----------|
-| 0 | 4+ P1 anti-patterns present |
-| 1 | 2-3 P1 anti-patterns present |
-| 2 | 1 P1 or 3+ P2 anti-patterns present |
-| 3 | 1-2 P2 or 2+ P3 anti-patterns only |
-| 4 | Zero P1/P2 anti-patterns, at most 1 P3 |
-
-### 2. Color Quality (Weight: 15%)
-
-| Score | Criteria |
-|-------|----------|
-| 0 | No color system; hex/rgb throughout; pure black/white used |
-| 1 | Some tokens but not OKLCH; no tinted neutrals; contrast failures |
-| 2 | OKLCH used partially; tinted neutrals attempted; most contrast passes |
-| 3 | Full OKLCH; tinted neutrals; 60-30-10 applied; all WCAG AA passes; semantic tokens present |
-| 4 | Score-3 plus: primitive->semantic->component hierarchy; color-mix usage; light/dark themes complete |
-
-### 3. Typography Quality (Weight: 15%)
-
-| Score | Criteria |
-|-------|----------|
-| 0 | System/generic font only; no scale; no fluid sizing |
-| 1 | Generic font (Inter/Roboto/etc); basic size scale; no clamp() |
-| 2 | Distinctive font chosen; modular scale present; no fluid sizing |
-| 3 | Distinctive font; modular scale with clamp(); proper line-height; reading width constrained |
-| 4 | Score-3 plus: font-display swap with fallback metrics; caption/body/heading line-heights differentiated |
-
-### 4. Spacing & Layout (Weight: 12.5%)
-
-| Score | Criteria |
-|-------|----------|
-| 0 | Arbitrary spacing; no system; nested cards |
-| 1 | Some consistent spacing but not 4pt scale; margin-heavy |
-| 2 | 4pt scale used; mostly gap over margin; some rhythm variation |
-| 3 | Full 4pt scale; gap throughout; rhythm variation (tight/comfortable/generous); touch targets met |
-| 4 | Score-3 plus: container queries used; no nested cards; 8px adjacent target gaps |
-
-### 5. Motion & Animation (Weight: 10%)
-
-| Score | Criteria |
-|-------|----------|
-| 0 | Layout property animations; no easing system; no reduced-motion |
-| 1 | Some transform/opacity; default ease/linear; no reduced-motion |
-| 2 | Transform/opacity only; custom easing present; reduced-motion exists but incomplete |
-| 3 | All animations on safe properties; ease-out-quart default; duration tokens; complete reduced-motion |
-| 4 | Score-3 plus: stagger system; will-change managed via JS; exit = 75% entrance |
-
-### 6. Interaction States (Weight: 15%)
-
-| Score | Criteria |
-|-------|----------|
-| 0 | Only default state; no hover/focus/disabled |
-| 1 | 2-3 states (e.g., default + hover + disabled) |
-| 2 | 5 states (default/hover/focus/active/disabled) but missing loading/error/success |
-| 3 | All 8 states defined; :focus-visible used; hover in @media(hover:hover) |
-| 4 | Score-3 plus: focus ring spec (2px solid + offset 2px); active scale(0.97); ARIA attributes on all states |
-
-### 7. Visual Hierarchy (Weight: 10%)
-
-| Score | Criteria |
-|-------|----------|
-| 0 | Everything same size/weight; no CTA hierarchy; all centered |
-| 1 | Some size variation; multiple primary CTAs per viewport |
-| 2 | Clear heading hierarchy; CTA levels present but inconsistent |
-| 3 | Passes squint test; single primary CTA per viewport; 3:1 size ratio; max 2 weights |
-| 4 | Score-3 plus: progressive disclosure; clear information density gradient |
-
-### 8. Responsive Design (Weight: 12.5%)
-
-| Score | Criteria |
-|-------|----------|
-| 0 | Fixed widths; breaks below 768px; content hidden on mobile |
-| 1 | Some media queries; horizontal scroll at 320px; small touch targets |
-| 2 | Mobile-first breakpoints; fluid widths; 14px min text; some issues at 320px |
-| 3 | Full breakpoint coverage; fluid design (clamp/vw/fr); 44px targets; no 320px scroll |
-| 4 | Score-3 plus: container queries; adapt-don't-hide approach; fluid typography |
-
----
-
-## Rating Bands
-
-| Score | Band | Meaning |
-|-------|------|---------|
-| 28-32 | Excellent | Production-ready, Impeccable quality |
-| 22-27 | Good | Minor polish needed, shippable |
-| 16-21 | Acceptable | Needs revision, core structure sound |
-| 10-15 | Poor | Significant rework required |
-| 0-9 | Critical | Fundamental issues, restart design phase |
-
-## Severity Mapping
-
-| Severity | Dimension Score | Action |
-|----------|----------------|--------|
-| P0 Blocking | Dimension = 0 | Must fix before any progress |
-| P1 Major | Dimension = 1 | Fix in current iteration |
-| P2 Minor | Dimension = 2 | Fix in next iteration |
-| P3 Polish | Dimension = 3 | Track for future improvement |
-
-## Signal Determination
-
-| Condition | Signal | Action |
-|-----------|--------|--------|
-| Score >= 26 AND no P0 (no dim at 0) | `audit_passed` (GC CONVERGED) | Unblock downstream |
-| Score >= 20 AND no P0 | `audit_result` (REVISION NEEDED) | Create fix task |
-| Score < 20 OR any P0 | `fix_required` (CRITICAL) | Urgent fix task |
+# 8-Dimension Quality Scoring Rubric
+
+Score each dimension 0-4. Total: 0-32.
+
+## Dimensions
+
+### 1. Anti-AI-Slop (Weight: 10%)
+
+| Score | Criteria |
+|-------|----------|
+| 0 | 4+ P1 anti-patterns present |
+| 1 | 2-3 P1 anti-patterns present |
+| 2 | 1 P1 or 3+ P2 anti-patterns present |
+| 3 | 1-2 P2 or 2+ P3 anti-patterns only |
+| 4 | Zero P1/P2 anti-patterns, at most 1 P3 |
+
+### 2. Color Quality (Weight: 15%)
+
+| Score | Criteria |
+|-------|----------|
+| 0 | No color system; hex/rgb throughout; pure black/white used |
+| 1 | Some tokens but not OKLCH; no tinted neutrals; contrast failures |
+| 2 | OKLCH used partially; tinted neutrals attempted; most contrast passes |
+| 3 | Full OKLCH; tinted neutrals; 60-30-10 applied; all WCAG AA passes; semantic tokens present |
+| 4 | Score-3 plus: primitive->semantic->component hierarchy; color-mix usage; light/dark themes complete |
+
+### 3. Typography Quality (Weight: 15%)
+
+| Score | Criteria |
+|-------|----------|
+| 0 | System/generic font only; no scale; no fluid sizing |
+| 1 | Generic font (Inter/Roboto/etc); basic size scale; no clamp() |
+| 2 | Distinctive font chosen; modular scale present; no fluid sizing |
+| 3 | Distinctive font; modular scale with clamp(); proper line-height; reading width constrained |
+| 4 | Score-3 plus: font-display swap with fallback metrics; caption/body/heading line-heights differentiated |
+
+### 4. Spacing & Layout (Weight: 12.5%)
+
+| Score | Criteria |
+|-------|----------|
+| 0 | Arbitrary spacing; no system; nested cards |
+| 1 | Some consistent spacing but not 4pt scale; margin-heavy |
+| 2 | 4pt scale used; mostly gap over margin; some rhythm variation |
+| 3 | Full 4pt scale; gap throughout; rhythm variation (tight/comfortable/generous); touch targets met |
+| 4 | Score-3 plus: container queries used; no nested cards; 8px adjacent target gaps |
+
+### 5. Motion & Animation (Weight: 10%)
+
+| Score | Criteria |
+|-------|----------|
+| 0 | Layout property animations; no easing system; no reduced-motion |
+| 1 | Some transform/opacity; default ease/linear; no reduced-motion |
+| 2 | Transform/opacity only; custom easing present; reduced-motion exists but incomplete |
+| 3 | All animations on safe properties; ease-out-quart default; duration tokens; complete reduced-motion |
+| 4 | Score-3 plus: stagger system; will-change managed via JS; exit = 75% entrance |
+
+### 6. Interaction States (Weight: 15%)
+
+| Score | Criteria |
+|-------|----------|
+| 0 | Only default state; no hover/focus/disabled |
+| 1 | 2-3 states (e.g., default + hover + disabled) |
+| 2 | 5 states (default/hover/focus/active/disabled) but missing loading/error/success |
+| 3 | All 8 states defined; :focus-visible used; hover in @media(hover:hover) |
+| 4 | Score-3 plus: focus ring spec (2px solid + offset 2px); active scale(0.97); ARIA attributes on all states |
+
+### 7. Visual Hierarchy (Weight: 10%)
+
+| Score | Criteria |
+|-------|----------|
+| 0 | Everything same size/weight; no CTA hierarchy; all centered |
+| 1 | Some size variation; multiple primary CTAs per viewport |
+| 2 | Clear heading hierarchy; CTA levels present but inconsistent |
+| 3 | Passes squint test; single primary CTA per viewport; 3:1 size ratio; max 2 weights |
+| 4 | Score-3 plus: progressive disclosure; clear information density gradient |
+
+### 8. Responsive Design (Weight: 12.5%)
+
+| Score | Criteria |
+|-------|----------|
+| 0 | Fixed widths; breaks below 768px; content hidden on mobile |
+| 1 | Some media queries; horizontal scroll at 320px; small touch targets |
+| 2 | Mobile-first breakpoints; fluid widths; 14px min text; some issues at 320px |
+| 3 | Full breakpoint coverage; fluid design (clamp/vw/fr); 44px targets; no 320px scroll |
+| 4 | Score-3 plus: container queries; adapt-don't-hide approach; fluid typography |
+
+---
+
+## Rating Bands
+
+| Score | Band | Meaning |
+|-------|------|---------|
+| 28-32 | Excellent | Production-ready, Impeccable quality |
+| 22-27 | Good | Minor polish needed, shippable |
+| 16-21 | Acceptable | Needs revision, core structure sound |
+| 10-15 | Poor | Significant rework required |
+| 0-9 | Critical | Fundamental issues, restart design phase |
+
+## Severity Mapping
+
+| Severity | Dimension Score | Action |
+|----------|----------------|--------|
+| P0 Blocking | Dimension = 0 | Must fix before any progress |
+| P1 Major | Dimension = 1 | Fix in current iteration |
+| P2 Minor | Dimension = 2 | Fix in next iteration |
+| P3 Polish | Dimension = 3 | Track for future improvement |
+
+## Signal Determination
+
+| Condition | Signal | Action |
+|-----------|--------|--------|
+| Score >= 26 AND no P0 (no dim at 0) | `audit_passed` (GC CONVERGED) | Unblock downstream |
+| Score >= 20 AND no P0 | `audit_result` (REVISION NEEDED) | Create fix task |
+| Score < 20 OR any P0 | `fix_required` (CRITICAL) | Urgent fix task |

package/.agents/skills/team-uidesign/specs/ux-writing.md

@@ -1,86 +1,86 @@
-# UX Writing Standards
-
-Guidelines for all text content in UI components. From Impeccable's UX writing reference.
-
----
-
-## Button Labels
-
-- **NEVER**: "OK", "Submit", "Yes", "No", "Cancel" (generic)
-- **ALWAYS**: verb + object — "Save changes", "Create account", "Delete message"
-- Destructive actions: name the destruction + show count — "Delete 5 items" not "Delete selected"
-- Primary CTA: specific benefit — "Start free trial" not "Get started"
-
-## Error Messages
-
-Formula: (1) What happened + (2) Why + (3) How to fix
-
-| Type | Template |
-|------|----------|
-| Format | "{Field} must be {format}. Example: {example}" |
-| Required | "{Field} is required to {reason}" |
-| Permission | "You don't have access to {resource}. Contact {who} for access" |
-| Network | "Couldn't reach the server. Check your connection and try again" |
-| Server | "Something went wrong on our end. Try again in a few minutes" |
-
-- Never blame user: "Please enter..." not "You entered..."
-- Never use codes alone: "Error 404" → "Page not found"
-- Be specific: "Password must be 8+ characters with a number" not "Invalid password"
-
-## Empty States
-
-Three components: (1) Acknowledge + (2) Explain value + (3) Provide action
-
-| Context | Example |
-|---------|---------|
-| First use | "No projects yet. Create your first project to get started. [Create project]" |
-| Search | "No results for '{query}'. Try a different search term or [browse all]" |
-| Filtered | "No items match these filters. [Clear filters]" |
-| Error | "Couldn't load items. [Try again]" |
-
-## Loading States
-
-- Be specific: "Saving your draft..." not "Loading..."
-- Multi-step: show progress — "Uploading (2 of 5 files)..."
-- Duration hint: "This usually takes about 30 seconds"
-
-## Confirmation Dialogs
-
-- Use sparingly — prefer undo over confirm
-- Title: what will happen — "Delete this project?"
-- Body: consequences — "This will permanently delete 12 files. This can't be undone."
-- Buttons: specific — "Delete project" / "Keep project" (not OK/Cancel)
-
-## Voice & Tone
-
-- **Voice**: consistent brand personality (professional/friendly/technical — choose one)
-- **Tone**: adapts to moment — cheerful for success, empathetic for errors, neutral for routine
-- Keep consistent: same word for same concept everywhere (delete/remove/trash → pick one)
-
-## Form Instructions
-
-- Show format with placeholder: `placeholder="john@example.com"`
-- Explain non-obvious fields with helper text below label
-- Mark optional fields (not required ones) — most fields should be required
-- Group related fields with clear section headers
-
-## Translation Planning
-
-| Language | Length vs English |
-|----------|------------------|
-| German | +30% |
-| French | +20% |
-| Finnish | +30-40% |
-| Chinese | -30% |
-| Japanese | -10-20% |
-
-- Design for longest language (German)
-- Never truncate translated text — allow wrapping
-- Avoid idioms and cultural references in source text
-
-## Redundant Copy Detection
-
-- Don't repeat visible information (heading ≠ first paragraph)
-- Labels describe the field, not restate the value
-- Tooltips add information, not repeat the label
-- If heading says it all, skip the intro paragraph
+# UX Writing Standards
+
+Guidelines for all text content in UI components. From Impeccable's UX writing reference.
+
+---
+
+## Button Labels
+
+- **NEVER**: "OK", "Submit", "Yes", "No", "Cancel" (generic)
+- **ALWAYS**: verb + object — "Save changes", "Create account", "Delete message"
+- Destructive actions: name the destruction + show count — "Delete 5 items" not "Delete selected"
+- Primary CTA: specific benefit — "Start free trial" not "Get started"
+
+## Error Messages
+
+Formula: (1) What happened + (2) Why + (3) How to fix
+
+| Type | Template |
+|------|----------|
+| Format | "{Field} must be {format}. Example: {example}" |
+| Required | "{Field} is required to {reason}" |
+| Permission | "You don't have access to {resource}. Contact {who} for access" |
+| Network | "Couldn't reach the server. Check your connection and try again" |
+| Server | "Something went wrong on our end. Try again in a few minutes" |
+
+- Never blame user: "Please enter..." not "You entered..."
+- Never use codes alone: "Error 404" → "Page not found"
+- Be specific: "Password must be 8+ characters with a number" not "Invalid password"
+
+## Empty States
+
+Three components: (1) Acknowledge + (2) Explain value + (3) Provide action
+
+| Context | Example |
+|---------|---------|
+| First use | "No projects yet. Create your first project to get started. [Create project]" |
+| Search | "No results for '{query}'. Try a different search term or [browse all]" |
+| Filtered | "No items match these filters. [Clear filters]" |
+| Error | "Couldn't load items. [Try again]" |
+
+## Loading States
+
+- Be specific: "Saving your draft..." not "Loading..."
+- Multi-step: show progress — "Uploading (2 of 5 files)..."
+- Duration hint: "This usually takes about 30 seconds"
+
+## Confirmation Dialogs
+
+- Use sparingly — prefer undo over confirm
+- Title: what will happen — "Delete this project?"
+- Body: consequences — "This will permanently delete 12 files. This can't be undone."
+- Buttons: specific — "Delete project" / "Keep project" (not OK/Cancel)
+
+## Voice & Tone
+
+- **Voice**: consistent brand personality (professional/friendly/technical — choose one)
+- **Tone**: adapts to moment — cheerful for success, empathetic for errors, neutral for routine
+- Keep consistent: same word for same concept everywhere (delete/remove/trash → pick one)
+
+## Form Instructions
+
+- Show format with placeholder: `placeholder="john@example.com"`
+- Explain non-obvious fields with helper text below label
+- Mark optional fields (not required ones) — most fields should be required
+- Group related fields with clear section headers
+
+## Translation Planning
+
+| Language | Length vs English |
+|----------|------------------|
+| German | +30% |
+| French | +20% |
+| Finnish | +30-40% |
+| Chinese | -30% |
+| Japanese | -10-20% |
+
+- Design for longest language (German)
+- Never truncate translated text — allow wrapping
+- Avoid idioms and cultural references in source text
+
+## Redundant Copy Detection
+
+- Don't repeat visible information (heading ≠ first paragraph)
+- Labels describe the field, not restate the value
+- Tooltips add information, not repeat the label
+- If heading says it all, skip the intro paragraph