Skip to content

docs(skills): realign the authoring guide with the current schema #107

Description

@LeadcodeDev

Part of #102 — wave 1.

Mini-spec

Goal: realign the authoring documentation with the schema the code actually accepts. This corpus is the de-facto schema (~63k tokens), so its drift translates directly into broken generations.

Invariants

  • Every JSON snippet in the documentation validates against the current binary.
  • No rule contradicts another rule on the same topic.

Out of scope: deleting LayerStyle from the code (L4 owns that); restructuring SKILL.md into a loader-based split (tracked separately if wanted).

Acceptance — each verified by extracting the snippet and running validate:

  • fill / stroke documented at component root, not inside style — 6 sites including "Example 1: Marketing Card" (SKILL.md:284, :837, :844-845, :1048, :1066-1068).
  • timeline / stagger documented at root (SKILL.md:2251-2252, :2306-2320, :1131).
  • box-shadow documented as an array with kebab-case keys (SKILL.md:1104, :2290).
  • flex-wrap documented as an enum, not a bool (SKILL.md:1107).
  • grid-template-columns reduced to the one valid syntax (SKILL.md:1081, :1111, icon-sizing-hierarchy.md:106).
  • motion-path and style.size removed (SKILL.md:2250, wiggle-additive.md:26).
  • transform documented as an array of transform functions, not a CSS string (depth-layering.md:109-111).
  • text-background documented at root (text-background.md:10-19).
  • geometry-safety.md rewritten around white-space; CLAUDE.md:19 stops describing style.wrap.
  • CLAUDE.md component count corrected to 57, qrcodeqr_code, and qr_code / waveform / audio_spectrum documented.
  • The background $ref example in color-palettes.md:100-118 fixed — it currently validates but renders a black frame.
  • Contradictions resolved: SKILL.md:1041 vs :1122 on position inside card; the end_at-on-counter examples that violate the checklist at SKILL.md:2523; the preset counts (31 / 45 / 39 — actual is 40 + 6 char); the easing count (11 documented, 17 + cubic_bezier actual).
  • The 4 orphaned rules present on main are linked from SKILL.md, and the 7 repo examples are referenced — they are currently more correct than the prose.

Files: CLAUDE.md, .claude/skills/rustmotion/**

Verify — extract every fenced JSON block and validate it:

rtk cargo build --release

then run each documented snippet through ./target/release/rustmotion validate.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions