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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

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