Build with us
A small port of a large design system, transcribed one component at a time — and there is a great deal left to transcribe. A Svelte port is a long transcription, done a component at a time.
Everyone who lands one is on this wall. See contributors
Everyone who lands one is on this wall. See contributors
How we build together
Contributing here means matching Astryx, not improving on it — an invented prop or a nicer default is a defect. Each step has a gate, and the third one is a script rather than an opinion. This is the Svelte port's process, not upstream's. Astryx incubates new components in @astryxdesign/lab; there is no @astryx-svelte/lab, so the gate here is the class oracle instead.01
Read upstream first
Astryx’s source is cloned at reference/astryx-upstream. Read the component, its .doc.mjs, its tests and the compiled dist/ before writing a line. If it is not in Astryx, it is not here.02
Port it
Author the .stylex.ts against the same token references upstream uses, then the component around it. React idioms translate; the public API does not change on the way across.03
Prove the CSS
The class oracle compiles your module and diffs the emitted atomic classes against upstream’s published dist/. Byte-identical, or it does not land. A deferral is an explicit skip with a reason.04
Audit
Three agents read the result: astryx-parity for the API surface, astryx-idiom for the Svelte translation, astryx-test-parity for the suite — ported case for case, because the count is the contract.Fix a bug
A crash, a wrong render, a prop that does nothing. File it with a reproduction and the form asks for the rest. ~2 hoursImprove the docs
This site is docs/ in the repo. Fix a typo, sharpen an example, or write down a translation that took you three reads. ~30 minResources
Contributing
- Contributing Guide The parity rule and how to take its exception, setup, the oracles, and the six steps a change goes through.
- Contributing with AI Five subagents encoding this port’s failure modes: astryx-parity, astryx-idiom, astryx-oracle, astryx-test-parity, astryx-surface.
- Dev Setup Install, build, and run the docs site and both fidelity oracles locally.
- Astryx (upstream) Meta’s React original, and the specification this port is measured against. Read it before proposing an API change.
- API Conventions (upstream wiki) How components in Astryx are named, shaped, and composed. Upstream’s page, deliberately not forked.
- API Arbitration (upstream wiki) How upstream settles design disagreements using vibe testing. Its verdicts bind this port too.
Communications
- GitHub Issues File bugs and feature requests against the Svelte port. Meta’s tracker is for the React library.
- Report a parity bug The report this port most needs: a place where a component behaves differently from Astryx. The form asks for the upstream behaviour.
- GitHub Discussions Questions, porting notes, and “is this a bug or a deliberate divergence?” — before it is an issue.
- Discord (upstream) The Astryx community server, run upstream. The people there work in React; the design questions are the same.