원클릭으로 Manus에서 모든 스킬 실행

spec-first

스타7

포크3

업데이트2026년 5월 10일 17:22

Spec-first development loop for motion components — define the types contract and observable behavior before writing any implementation code, then implement to match the spec. Prevents drift between intent and code.

설치

Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.

Manus에서 실행

출처

tgomilar

tgomilar/motion-components

GitHub 저장소 열기 Creator 저장소 보기

다운로드

Manus에서 실행

spec-first

This project has no test framework. Instead, enforce a spec-first loop: define the complete contract (types, props, observable behavior) before writing a single line of animation or rendering code. Implementation must satisfy the spec, not the reverse. The loop is: red → green → refactor.

The loop

Red — define the contract first

Before any implementation:

Write <tag>.types.ts — every prop, its type, and its default value. If a type can't be expressed clearly, the design is incomplete. Fix that first.
Write the docs page stub — create the Astro docs page with the <PropsTable> filled in for every attribute. The table IS the spec. If a prop is ambiguous to document, it's ambiguous to implement.
Write the JSDoc on the class — @element, @slot, @example. This is the public contract. It must be complete before render() is written.

"Red" = the component doesn't exist yet, so any attempt to use it would fail.

Green — implement to satisfy the spec

Create <tag>.ts with the skeleton: @property declarations matching the types file exactly, static styles, and an empty render().
Implement the animation using Motion One. Every prop in the types file must be wired to the animation. No extra props, no missing props.
Check props match docs — compare <PropsTable> attributes against @property declarations. Every discrepancy is a bug.
Run npx tsc --noEmit — zero errors required. This is your "green" gate.

"Green" = the component exists and matches the spec.

Refactor — clean up without breaking the contract

Simplify animation code — extract repeated animate() calls, consolidate spring params into a getter, remove dead branches.
Verify reduced-motion — check the prefers-reduced-motion branch applies the final state instantly and doesn't skip accessibility affordances.
Re-run typecheck — still zero errors.

"Refactor" = same observable behavior, cleaner code.

Rules

Never write <tag>.ts before <tag>.types.ts exists and is complete.
Never merge props into the types file after implementation starts — that's the spec drifting to match the code. Stop, update the docs table instead, then update types, then update code.
If a prop is "nice to have" but not in the PRD, it doesn't go in the types file. Add it in a follow-up cycle.
The <PropsTable> on the docs page is the living spec. It must match the types file exactly at all times.

Quick checklist

Before calling any issue "done", verify:

<tag>.types.ts matches every @property in <tag>.ts
<PropsTable> lists every attribute with correct type and default
JSDoc @example is a working snippet
prefers-reduced-motion branch exists and is tested manually
npx tsc --noEmit exits 0

References

Implementation scaffolding: new-component skill (.claude/skills/new-component/SKILL.md)
Style conventions: style-guide skill (.claude/skills/style-guide/SKILL.md)
Release gate: release skill (.claude/skills/release/SKILL.md)

이 저장소의 다른 Skills

같은 저장소

new-component

tgomilar/motion-components

Scaffold a new motion-* web component end-to-end — TypeScript source, types file, Vite build entry, package.json subpath export, src/index.ts re-export, and a docs page. Use when the user asks to add, scaffold, or create a new component named like motion-X.

2026-07-137

audit

tgomilar/motion-components

Audit the codebase for animation primitive violations, duplicated animation logic, composition opportunities, and architectural drift. Produces a prioritized list of improvements with specific file locations.

2026-05-107

clarify

tgomilar/motion-components

Ask focused clarifying questions before building any new component or feature. Forces shared understanding of animation behavior, props API, trigger conditions, accessibility, and done criteria BEFORE writing any code.

2026-05-107

plan

tgomilar/motion-components

Turn a vague component idea or feature request into a structured Product Requirements Document covering purpose, props API, animation behavior spec, accessibility, and docs structure. Use before implementing anything non-trivial.

2026-05-107

release

tgomilar/motion-components

Run pre-publish verification for the motion-components package — typecheck, preload-rule check, library build, and bundle size budget. Use before bumping the version or running npm publish.

2026-05-107

style-guide

tgomilar/motion-components

The motion-components project conventions — code style, component architecture, animation rules, doc page structure, naming, and what NOT to do. Reference this whenever editing source, adding components, or writing docs pages.

2026-05-107

name	spec-first
description	Spec-first development loop for motion components — define the types contract and observable behavior before writing any implementation code, then implement to match the spec. Prevents drift between intent and code.

spec-first

The loop

Red — define the contract first

Before any implementation:

Write <tag>.types.ts — every prop, its type, and its default value. If a type can't be expressed clearly, the design is incomplete. Fix that first.
Write the docs page stub — create the Astro docs page with the <PropsTable> filled in for every attribute. The table IS the spec. If a prop is ambiguous to document, it's ambiguous to implement.
Write the JSDoc on the class — @element, @slot, @example. This is the public contract. It must be complete before render() is written.

"Red" = the component doesn't exist yet, so any attempt to use it would fail.

Green — implement to satisfy the spec

Create <tag>.ts with the skeleton: @property declarations matching the types file exactly, static styles, and an empty render().
Implement the animation using Motion One. Every prop in the types file must be wired to the animation. No extra props, no missing props.
Check props match docs — compare <PropsTable> attributes against @property declarations. Every discrepancy is a bug.
Run npx tsc --noEmit — zero errors required. This is your "green" gate.

"Green" = the component exists and matches the spec.

Refactor — clean up without breaking the contract

Simplify animation code — extract repeated animate() calls, consolidate spring params into a getter, remove dead branches.
Verify reduced-motion — check the prefers-reduced-motion branch applies the final state instantly and doesn't skip accessibility affordances.
Re-run typecheck — still zero errors.

"Refactor" = same observable behavior, cleaner code.

Rules

Never write <tag>.ts before <tag>.types.ts exists and is complete.
Never merge props into the types file after implementation starts — that's the spec drifting to match the code. Stop, update the docs table instead, then update types, then update code.
If a prop is "nice to have" but not in the PRD, it doesn't go in the types file. Add it in a follow-up cycle.
The <PropsTable> on the docs page is the living spec. It must match the types file exactly at all times.

Quick checklist

Before calling any issue "done", verify:

<tag>.types.ts matches every @property in <tag>.ts
<PropsTable> lists every attribute with correct type and default
JSDoc @example is a working snippet
prefers-reduced-motion branch exists and is tested manually
npx tsc --noEmit exits 0

References

Implementation scaffolding: new-component skill (.claude/skills/new-component/SKILL.md)
Style conventions: style-guide skill (.claude/skills/style-guide/SKILL.md)
Release gate: release skill (.claude/skills/release/SKILL.md)