Ios design system atoms

iOS Design System Atoms

Goal

Generate every foundational atom needed to implement an iOS design system from reference images. The final artifact is always parser-valid YAML using the contract in references/atoms-yaml-contract.md.

An atom is a reusable lowest-level design primitive: color, type, spacing, sizing, layout, shape, stroke, elevation, material, opacity, gradient, texture, icon, image treatment, motion, haptic, sound, copy, and z-index token. Every atom must include static values and dynamic adaptation rules.

Non-Negotiables

• Start from reference images. If no visual reference or already-extracted visual design-system YAML is available, ask for it before generating atoms.
• Invoke visual-design-system-extractor with the reference images first. Use its validated YAML output as the source visual system for atom extrapolation.
• Final output must be YAML only unless the user explicitly asks for package maintenance, explanation, or files.
• Preserve the exact top-level order and required nested object shapes from references/atoms-yaml-contract.md.
• Do not emit null, empty strings, empty lists, empty mappings, undefined, unknown, missing, todo, tbd, n/a, or placeholder values.
• Do not use wall-clock timestamps, random IDs, or run-dependent values. Derive IDs from stable source order, source filenames, visible evidence, or a source fingerprint.
• If a field is not directly visible, fill it through a deterministic fallback and record the fallback in provenance.decision_rule with confidence: low.
• Every atom object must include static, dynamic, provenance, implementation, and qa sections.
• Dynamic adaptations are required even for visually simple atoms: light/dark, accessibility, interaction state, device context, locale direction, motion context, and data context.

Workflow

Progress:

• Confirm reference input.
• Run visual extraction.
• Normalize source evidence.
• Extrapolate static atoms.
• Extrapolate dynamic atoms.
• Validate YAML.

1. Confirm Reference Input

Proceed when the user supplies one of:

• attached reference images
• local image paths
• screenshots or moodboards
• a visual design-system YAML artifact from visual-design-system-extractor

If multiple references are supplied, preserve their order. Assign deterministic source IDs as ref_001, ref_002, and so on.

2. Run Visual Extraction

Use visual-design-system-extractor with the same reference images. Ask it for its native visual design-system YAML, not for iOS atoms.

The extractor output becomes extraction_bridge.visual_design_system_extractor.output_summary and drives these sections:

• static_atoms.color from extracted color, lighting, material, and accessibility evidence
• static_atoms.typography from extracted typography and rare typeface candidates
• static_atoms.spacing, layout, shape, and stroke from spacing, grid, sizing, borders, and radii
• static_atoms.elevation, material, opacity, gradient, and texture from surface treatment, shadow, gradient, and rendering evidence
• static_atoms.iconography and imagery from icon, illustration, rendering, and photography evidence
• static_atoms.motion, haptics, and sound from motion, interaction, tone, and platform adaptation evidence
• dynamic_atoms from extracted state variants, responsive rules, accessibility notes, and platform adaptations

If the extractor cannot run, stop and explain the blocked dependency. Do not invent image evidence.

3. Normalize Evidence

Before writing atoms, create a stable source fingerprint:

1. Prefer SHA-256 of ordered image bytes when local files are available.
2. Otherwise hash ordered source IDs, filenames, dimensions if known, and extractor meta fields.
3. Use the first 12 lowercase hex characters in determinism.source_fingerprint.

Separate direct visual evidence, deterministic iOS defaults, and extrapolated values in each atom's provenance object. Do not collapse weak evidence into direct evidence.

4. Generate Atom Inventory

Read references/atoms-yaml-contract.md before producing the final YAML.

Create all required static atom categories:

• color
• typography
• spacing
• sizing
• layout
• shape
• stroke
• elevation
• material
• opacity
• gradient
• texture
• iconography
• imagery
• motion
• haptics
• sound
• copy
• z_index

Use deterministic token IDs:

atom.<category>.<role>.<variant>

Examples:

atom.color.surface.primary
atom.typography.body.default
atom.motion.spring.emphasized

Every token must include the required atom object fields from the contract. Use iOS-native implementation mappings where possible: SwiftUI Color, Font, Material, Animation, SymbolEffect, SensoryFeedback, Layout, and UIKit equivalents.

5. Generate Dynamic Adaptations

Create every required dynamic atom section:

• color_scheme_adaptations
• accessibility_adaptations
• interaction_state_adaptations
• device_context_adaptations
• locale_context_adaptations
• motion_context_adaptations
• data_context_adaptations
• system_material_adaptations

Each dynamic section must specify:

• rule_id
• affected_atom_categories
• default_behavior
• variants
• implementation_notes

Variants must be concrete and non-empty. If reference images do not show a variant, derive it from the base atom and record that derivation.

6. Validate

When shell tools are available, draft the YAML to a temporary file and run:

uv run scripts/validate-ios-atoms-yaml.py /tmp/ios-design-system-atoms.yaml

If PyYAML is installed directly, run python3 scripts/validate-ios-atoms-yaml.py /tmp/ios-design-system-atoms.yaml.

Fix all reported errors before returning or saving the artifact. If validation cannot run, manually check every item in quality_gates.validation_checks and report the limitation.

Gotchas

• Do not treat dynamic as runtime metadata. It means adaptive design behavior across iOS contexts.
• Do not use "unknown" for weak evidence. Choose a deterministic fallback, lower the confidence, and explain the rule.
• Do not emit empty optional-looking structures. If a section is required, it must contain at least one concrete value.
• Do not add top-level sections for convenience. Put additions under the nearest existing mapping using snake_case keys.
• Do not browse for brand, font, or product comparisons unless the user explicitly asks. The visual extractor and the reference images are the source of truth.

Support Files

• references/atoms-yaml-contract.md: canonical YAML schema, key order, atom object shape, category requirements, and deterministic fallback rules.
• references/agent-skills-compliance.md: package-maintenance and publication guidance.
• scripts/schema_tools.py: prints contract sections and the canonical top-level skeleton for quick reference.
• scripts/validate-ios-atoms-yaml.py: mechanical YAML validation for top-level order, required nested fields, atom object shape, confidence values, and banned placeholder values.