-
Notifications
You must be signed in to change notification settings - Fork 28
Component Lifecycle
The full journey from "we need a component" to "it's production-quality and stays that way." Three phases, each with its own protocol, connected by shared tools that keep quality high throughout.
┌─────────────────────────────────────────────────────────────┐
│ │
│ SPECIFY ──────► BUILD ──────► HARDEN │
│ │
│ What to build Build it Make it correct, │
│ and why right complete, and polished │
│ │
│ ◄──────────────────────────────────────────────┘ │
│ Findings that exceed hardening scope │
│ route back to specification │
│ │
├─────────────────────────────────────────────────────────────┤
│ │
│ MAINTAIN (ongoing) │
│ Nightly auditor enforces conventions as the │
│ system evolves — catches drift before it ships │
│ │
└─────────────────────────────────────────────────────────────┘
Not everything needs a new component. Before starting the spec protocol, answer these questions:
| Question | If yes... |
|---|---|
| Can existing components compose to solve this? | Write a recipe/example in the sandbox instead |
| Is the need domain-specific to one product? | It's a recipe, not a core component |
| Is it a visual variation of something that exists? | Explore theming or xstyle overrides first |
| Does it add behavior to an existing component? | Consider a prop addition (still needs the spec protocol, but lighter) |
If the answer to all of these is "no" — you're building a new component. Read on.
Before diving in, familiarize yourself with:
- API Conventions — Naming rules, prop patterns, composition vs config, styling escape hatches
- Component Authoring Guide — File structure, StyleX patterns, token usage, templates
- Contributing with AI Assistants — The full contribution protocol (especially if working with an AI assistant)
Goal: Decide what to build, why, and what the API should look like — backed by evidence, not opinion.
Protocol: Component Specification Protocol
| Step | What happens |
|---|---|
| Triage | Is this a core component, or can existing ones compose to solve it? |
| Research (internal) | Code search across internal and open source usage. Usage data, prop frequency, workaround patterns. |
| Research (external) | Compare with Radix, shadcn, Ant, MUI, Chakra. Where has the industry converged? |
| Enumerate use cases | Exhaustive list of scenarios the API must handle: simple, configured, controlled, composed, edge, migration. |
| Draft spec | The problem, use cases, architecture, API (with rationale), behavior, composition stories. |
| Surface area audit | Every proposed export checked against existing components. No duplicates. |
| Spec review | 6-phase review: understand → cross-reference → competitive analysis → apply principles → composition & defaults → resolve uncertainty. |
| API Arbitration | Test candidate API shapes with naive prompts. Override rate and escape hatches decide. |
| Finalize | Spec becomes the contract for the build phase. |
Key principle: Port the value, not the internal structure. Internal architecture reflects internal constraints that may not apply to OSS.
Naming decisions are never made by opinion. If naming is contested, API Arbitration runs and LLM results decide.
Output: An approved spec with a tracking issue. → Proceed to Build.
Goal: Implement the spec correctly, with tests, stories, documentation, and a clean PR.
Protocol: Component Build Protocol
| Step | What happens |
|---|---|
| Setup | Read the spec. Check dependencies. Create worktree and branch. |
| Foundation | Types, interfaces, skeleton. Wire up exports. |
| System integration | Verify theming, overlay patterns, layout composition work. |
| Implementation | Compose from existing Astryx components. Tokens everywhere. Hover guards. Slots are passthrough. |
| Status states | Error/warning/success border treatment (if input). |
| Stories | Demonstrate differences, not just enumerate. Show composition and edge cases. |
| Tests | Behavior, keyboard, ARIA. |
| Documentation | Typed .doc.mjs file. |
| PR | Link to spec issue. CI must pass. |
| Self-review | Post the checklist on the PR (see Self-Review). |
| Refinement loop | Drive CI to green (see PR Refinement Loop). |
| Review response | Address human feedback. Update spec if needed. |
Key principle: The spec is the contract. Deviations need justification.
Output: A merged PR. → Proceed to Hardening.
Goal: Verify the component is correct, complete, and polished. Fix bugs, tighten visual quality, surface design decisions.
Protocol: Component Hardening Protocol
Hardening operates in three layers:
| Layer | Executor | What it covers |
|---|---|---|
| Automated audit | Navi / CI | Tokens, naming, theming, a11y contracts, exports — objective pass/fail |
| Bug & visual fixes | Navi + human review | State coverage, visual correctness, keyboard, edge cases, family consistency |
| Design review | Human (with Navi prep) | Proportions, interaction feel, composition quality — structured form with constrained answers |
Key principle: Hardening makes Astryx consistent with itself. Not with WWW, not with external systems — with its own conventions, tokens, and family contracts. If a finding needs a new prop or imports a feature from elsewhere, it routes back to specification.
Naming concerns surface during hardening but are never resolved there. They get queued for a vibe test — LLM results decide, not human opinion.
Output: A production-quality component. Findings that exceed hardening scope become spec issues, closing the loop.
The Night Watch Component Auditor runs every night against all components. It enforces the same conventions that Layer 1 of hardening checks — but continuously, not just during a hardening pass.
- Audits 5 components per night (rotating queue)
- Checks all 9 audit dimensions: tokens, xdsThemeProps, component reuse, prop naming, type naming, structure, input consistency, accessibility contracts, export hygiene
- Batches findings into a single PR per night
- Drives the PR to green via the PR Refinement Loop
Components regress silently. A hardcoded color sneaks in. A new variant forgets xdsThemeProps. A refactor drops displayName. None of these break tests or CI — but they break the developer and theming contracts. The auditor catches drift before it compounds.
When a system-level design decision is made (motion, edge compensation, density), it gets specced through the specification protocol and encoded as a wiki reference page. The auditor then checks components against that spec:
Design decision → Spec loop → Wiki spec → Auditor references it → Components converge
This means hardening gets more powerful over time without getting more manual. Each wiki spec you write extends the auditor's coverage.
These tools are used across the build and hardening phases. They're not phases themselves — they're capabilities the team reaches for when needed.
A structured checklist posted on every PR as a review comment. It leaves a paper trail — the reviewer sees what you've already checked, and skips re-verifying those items.
Two versions:
| Version | When to use | Items |
|---|---|---|
| Full (27 items) | New components | Composition, theming, icons, xdsThemeProps, wrapper divs, hover guards, elevation, spacing, shorthands, ARIA, useEffect smells, slot consistency, family alignment, naming, escape hatches, extraction, hooks, status states, stories, theming story, defaults, shared implementation, spec compliance, surface area, system integration, standalone extractions, local tests |
| Quick (8 items) | Refactors and updates | Icons from registry, xdsThemeProps present, no wrapper divs, no CSS shorthands, ARIA still correct, tests pass, stories updated, popover background |
The full checklist is in Component Build Protocol Phase 10. Use it during both build (on the initial PR) and hardening (on fix PRs).
The feedback cycle between pushing code and getting CI results. The goal: by the time a human looks at the PR, every automated check is passing.
Push → Wait for CI (~5 min) → Read results → Fix locally → Push → Repeat
Safety rules:
- SHA check before every fix — if the HEAD changed and you didn't push it, someone else is working on the branch. Stop.
-
Fix locally first — run
pnpm test && pnpm build && pnpm lintbefore pushing. Don't use CI as your test runner. - 3 attempt limit — if still failing after 3 rounds, log the state and request human review.
What to fix vs. flag:
| Fix it | Flag it |
|---|---|
| Lint, type errors, test failures from your changes | Flaky tests that pass locally |
| Missing imports, build config issues | Pre-existing failures on main |
| Timeouts, infrastructure issues |
The rule: fix what your PR caused. Flag what it didn't.
The refinement loop is used during build (Phase 9 → green PR) and hardening (Layer 2 fix PRs). The Night Watch Component Auditor also uses it to drive nightly audit PRs to green autonomously.
Lessons learned from real PRs that didn't land.
"I already know what the API should look like."
Maybe. But the spec protocol isn't just about the final API — it's about the evidence behind it. Usage data, cross-system comparison, composition stories. Without those, reviewers can't evaluate whether the API is right, and you can't defend your decisions when they push back.
"Internal Astryx has
InternalListItemContentso we need that too."
Internal architecture reflects internal constraints (backward compatibility, internal tooling hooks, team-specific patterns). OSS architecture should reflect the value being delivered. Port the what, not the how.
"This component needs a Separator sub-component."
Does it? Or should it use Divider, which already exists? The surface area audit (Spec Phase 6) catches this. Every proposed export must justify its existence against what already exists in Astryx.
"I set the padding to 12px."
Use spacingTokens.space3. Raw values bypass theming — when a consumer changes their spacing scale, your component won't respond. This applies to colors, radii, shadows, transitions — everything. See the Token Usage section in Component Authoring Guide.
Three rounds of "should this be a hook or a prop?" with no resolution.
Stop debating. Build both options. Run a Vibe Tests. The override rate will tell you which API is right. This is how the Collapsible discussion went from circles to a clear answer.
Not everything found during hardening stays in hardening. The routing rule:
| Finding | Route |
|---|---|
| Wrong token, visual bug, broken state | Hardening — fix it |
| Family consistency gap (sibling components diverged) | Hardening — the system already decided this |
| Internal naming convergence (API contradicts its own tokens) | Hardening — self-consistency |
| Naming dispute (no clear right answer) | Vibe test → spec issue if winner emerges |
| New prop, new variant, new sub-component | → Component Specification Protocol |
| System-wide pattern (motion, edge compensation) | → Spec loop (system scope) |
| "WWW does it differently" | Research input only. File issue if it reveals a real gap. |
This routing keeps hardening focused on quality while ensuring feature work goes through proper specification.
| Topic | Page |
|---|---|
| Specification protocol (9 phases) | Component Specification Protocol |
| Build protocol (11 phases + checklists) | Component Build Protocol |
| Hardening protocol (3 layers + form) | Component Hardening Protocol |
| Nightly automated enforcement | Night Watch Component Auditor |
| API naming and structure rules | API Conventions |
| File structure, StyleX, tokens, templates | Component Authoring Guide |
| Evaluating API decisions with LLM testing | Vibe Tests |
| Contribution workflow with AI assistants | Contributing with AI Assistants |
| Creating a new component (redirect) | Creating New Components |