os.design

Custom agent imported from kiarashplusplus/delta-t-zaman (.github/agents/os.design.agent.md). Copyright stays with the author.

User Input

$ARGUMENTS

Prerequisites

Gate Check: Run bash .specify/scripts/bash/pipeline-audit.sh --phase 1 --json and verify ALL 12 Phase 1 artifacts are present. Then verify both persona-sim.md and ux-strategy.md exist in .specify/artifacts/phase-2/. If any artifact is missing, emit a gate violation and halt:

violation_type: "missing_artifact"
blocking_gate: "Phase 1 → Phase 2"
missing_artifacts:
  - name: "{artifact}"
    expected_path: "{path}"
    producing_agent: "{agent}"
remediation: "Run /{agent} to generate the missing artifact"

Constitutional Authority

• Law V (UX as Product Strategy) — Rules 5.3, 5.4

Design tokens and constraints MUST be derived from the UX strategy, not invented independently. Every token must trace back to a strategic requirement.

Execution

1. Translate UX strategy into design constraints: Read ux-strategy.md and extract every behavioral requirement that implies a visual or interactive constraint. Map each requirement to a concrete design decision.

2. Define design tokens:

   • Color system — Primary, secondary, accent, semantic colors (success, warning, error, info). Include dark mode variants. Define color roles, not just values.
   • Typography — Type scale (sizes, weights, line heights). Font family selections with fallback stacks. Reading-optimized settings for body text. RTL-compatible font selections.
   • Spacing — Base unit and scale (e.g., 4px base with multipliers). Component spacing rules. Page margin/padding standards.

3. Set accessibility requirements:

   • Contrast ratios (WCAG AA minimum: 4.5:1 for normal text, 3:1 for large text)
   • Touch target minimums (48×48dp per Material guidelines)
   • Minimum text sizes for body and UI elements
   • Focus indicator specifications
   • Screen reader annotation patterns

4. Define responsive breakpoints: Specify breakpoints with layout behavior at each tier. Map breakpoints to cognitive load constraints from UX strategy (e.g., fewer choices on smaller screens).

5. Specify animation/transition timing: Define duration scales (micro-interactions, page transitions, loading states). Specify easing curves. Set reduced-motion alternatives.

6. RTL language considerations: Critical for Persian poetry app context:

   • Bidirectional text rendering rules
   • Mirrored layout specifications
   • RTL-specific spacing and alignment
   • Mixed-direction content handling (Persian + English)
   • Nastaliq script rendering requirements (if applicable)

7. Traceability: Map EVERY design decision back to a specific UX strategy requirement. No orphan tokens — every value must have a justification chain: persona → UX strategy → design token.

Output

Write the following artifacts to .specify/artifacts/phase-2/:

design-tokens.md

Required sections:

• ## Color System — Full color palette with roles, values, dark mode variants, and semantic meanings.
• ## Typography — Type scale, font selections, line heights, RTL-compatible choices.
• ## Spacing — Base unit, scale, component spacing, page-level spacing.
• ## Accessibility — Contrast ratios, touch targets, text sizes, focus indicators, screen reader patterns.
• ## RTL Support — Bidirectional rendering, mirrored layouts, mixed-direction content, script-specific requirements.

design-constraints.md

Required sections:

• ## Layout Constraints — Grid system, responsive behavior, content width limits, breakpoint-specific rules.
• ## Interaction Constraints — Animation timing, transition specs, reduced-motion alternatives, gesture patterns.
• ## Performance Constraints — Asset size budgets, rendering performance targets, animation frame rate minimums.
• ## Responsive Breakpoints — Breakpoint values, layout behavior per tier, cognitive load adjustments per breakpoint.

Gate Criteria

• Every design token traces to a UX strategy requirement (no orphan tokens)
• Accessibility thresholds are explicit (contrast ratios as numbers, touch targets in dp/px)
• RTL support is fully specified (not deferred or marked as TODO)
• Responsive breakpoints map to cognitive load constraints from UX strategy
• Both design-tokens.md and design-constraints.md are produced

Self-Evaluation

Before writing the final artifact, evaluate your output against these criteria:

Rules:

• If any criterion scores below 3, identify the weakest section and revise it before producing the final output.
• Include the completed score table in a ## Quality Score section at the bottom of the output artifact.
• If you cannot score above 3 on Specificity due to missing upstream artifacts, note this explicitly — the loop runner will prioritize filling those gaps.