-
Notifications
You must be signed in to change notification settings - Fork 129
Contributing
Astryx is a design system with strong opinions about correctness, consistency, and LLM codegen quality. This document explains how contributions work, what we own, and what you can expect from us.
The guiding principle is: stricter about what goes in, less strict on how it's used. The contribution process has a high bar and real gates. But once something is in the system, we don't dictate how consumers use it — that flexibility is the point.
Read Astryx Philosophy for the full picture. Understanding it will help you write better RFCs and avoid proposals we're likely to decline.
Contributing to Astryx means contributing to the system, not to a component. Once something is in, it belongs to the system's coherence — not to the contributor's original intent. We will make adjustments as the system evolves, including breaking changes, without requiring contributor consent.
API decisions are not a matter of taste. All disputes are resolved through vibe testing and adherence to documented conventions — objective, reproducible, and documented.
The Astryx team holds final decision authority on system changes. A design system that serves many consumers needs someone accountable for the whole, not just the parts. The processes here — RFCs, vibe testing, documented conventions — exist so that every decision has clear reasoning you can engage with. We want contributors to bring strong arguments backed by evidence, and we take those arguments seriously. But the system has a long-term direction that any single contribution only sees part of, and sometimes the answer is "not yet" or "not this way" even when the evidence for a feature is real. When we decline or redirect, we'll explain why in terms you can challenge — and if your counter-argument is stronger, we'll change course. The process is how we stay accountable to the community while keeping the system coherent.
Open an issue first to confirm the behaviour is a bug, then submit a PR. Include a test, reproduction case, or documented manual verification step (including AT and browser combination for accessibility fixes). Keep PRs tightly scoped.
Components in the Astryx package are fully team-owned. The path for new additions:
- Propose via RFC — the problem, evidence of demand, and initial research
- We evaluate the RFC and either accept it as worth pursuing or decline with rationale
- Either of us drives the Component Specification Protocol — research, API exploration, use case enumeration. Contributors can front-load this work in the RFC itself (at their own risk if we decline later). As long as we haven't said no, you have agency to push this forward.
- The design brief crystallizes from that research — you'll see the work reflected in it
- You implement to the brief, or choose not to proceed
- Implementation lands in lab
- We review for graduation into core
The spec protocol is where the real design work happens — and it's open to contributors. The team applies system context and makes the final call, but the reasoning is visible and challengeable.
Once the brief is issued, it's the contract. If new evidence surfaces later, propose a re-test through the same process.
New props, variants, or behavioral changes to existing components go through the same Component Specification Protocol — but scoped to the specific ask. Before filing, check whether the feature belongs in the system at all:
- Can this be done with existing props or composition? If yes, it's a recipe — write a template or story showing how.
- Is this a general pattern or a one-product need? If it only makes sense in one context, it doesn't belong on a shared component.
- Does adding this make the component harder to use correctly? Every prop is a decision point. If the feature adds confusion for the 90% to serve the 10%, it's probably wrong.
If it passes all three, file an issue describing the problem (not the solution). The spec protocol applies but is lighter for feature additions — you likely don't need full external research or surface area audit, but you do need use case enumeration and may need API Arbitration if the right shape isn't obvious.
Reviewed for correctness, not just functionality. The bar is whether something demonstrates the right way to use Astryx. This matters because templates are training signal for LLMs. A bad example that works is worse than no example. See Contributing Templates.
Welcome. Goes through correctness review. Precision over comprehensiveness — doc length directly impacts LLM usage quality.
Lab is a staging area. Not distributed. The only way to consume lab components is to fork or clone — an explicit acknowledgment of no ownership expectation from us.
Lab is not a commitment to ship. Graduation happens when:
- The component is dogfooded and battle-tested
- The API has stabilized
- Vibe tests confirm discoverability
- Component Hardening Protocol passes
If a contribution stalls, we'll communicate clearly about its status.
An RFC is a problem statement and demand signal — not a design proposal we evaluate as written.
Include:
- The use case and evidence of demand
- Why existing components don't cover the need
- Rough approaches to show you've thought through the space
- Accessibility considerations
We aim to respond within 1 week — either a design brief, a request for more information, or a decline with rationale.
Two gates:
- Wiki adherence — prop naming, event patterns, token usage, composition model
- Vibe testing — does the API produce good LLM output? Is it discoverable? Does the model reach for the right component?
Both must pass. The design brief we issue reflects both.
Coming. Visual and interaction design is reviewed by our design team before graduation from lab to core.
See Contributing with AI Assistants for the full guide. The short version:
Safe zones (no protocol): stories, templates, sandbox pages, lab experiments, themes (see below).
Spec protocol required: any change to packages/core/.
For designers: themes give you full visual control via defineTheme(). Gap reports ("I tried to build X and couldn't") are the most valuable signal you can give. You don't need to write specs — your contribution is surfacing what's needed.
For AI-assisted workflows: point your tool at API Conventions and the CLI (npx astryx component <Name>). Don't let it skip the issue. Always gh pr create --draft.
Self-review AI output before requesting review. Review your AI's work before opening a PR — the same way you'd review your own code. Read every line, verify component usage against the CLI, and make sure nothing was hallucinated.
- Implementation PRs against core without a prior design brief
- Components that introduce external dependencies (core is zero-dependency)
- Themes that override cascade layer structure or misuse tokens
- Brand-specific themes (publish independently instead)
- Documentation that's comprehensive at the expense of signal clarity
Components rendering multiple items (lists, tables, grids) have additional scrutiny around DOM counts, virtualization, and measurement. Address these in your RFC.
If you're unsure whether something is worth an RFC, open a discussion first. We'd rather tell you early that something isn't a fit than have you invest in work we can't accept.
- Astryx Philosophy — How we think about building Astryx
- API Conventions — Naming, prop patterns, composition rules
- API Arbitration — How we resolve API disputes with vibe testing
- Component Lifecycle — Specify → build → harden
- Contributing with AI Assistants — Detailed AI contribution guide
- Contributing Templates — Page and block templates