-
Notifications
You must be signed in to change notification settings - Fork 27
Astryx Philosophy
How we think about building Astryx — the problems we're solving, what we've learned, and how we work. For anyone contributing to or collaborating on the system.
Component libraries have a common set of failure modes. These show up across the ecosystem — and we've felt them ourselves.
Ownership falls on the consumer. Copy-paste component models shift maintenance entirely to the developer. When upstream dependencies break, every app that copied the code has to fix it independently. The tradeoff between control and maintenance cost is real, and most teams underestimate the maintenance side.
Styling systems create lock-in. Coupling component logic to a specific styling approach means adopting the library also means adopting its CSS philosophy — whether or not that fits your project. Teams that want the components but not the styling framework are stuck.
Customization is either too hard or too shallow. Some libraries require dozens of lines of code just to change the colors of an input. Others offer full flexibility with no guardrails, and getting out takes more effort than building the thing yourself. The middle ground — deep customization with sensible constraints — is hard to find.
AI assistants struggle with component libraries. This is commonly attributed to libraries being out of distribution — not in the training data. But popular, well-known libraries have the same problems. The real issue is API complexity, implicit conventions, and poor error recovery paths.
Consistency breaks down at scale. Without strong conventions, different teammates implement the same component slightly differently, and the UI fragments. Once teams start forking components to fill gaps, they're maintaining a shadow version of the library on top of the product itself.
Designers and developers end up at odds. When a component library becomes the de facto design system, designers lose control of the visual language. The common advice — just build your own components — defeats the purpose of having shared components in the first place.
Strict systems burden the maintainer. The opposite extreme is just as costly. Tightly controlled design systems that gate every change through the system team create a bottleneck. As a maintainer, this means constantly negotiating between product teams that need to move and designers that need consistency — every update, every exception, every edge case funneled through the same people. The system becomes a dependency rather than an enabler, and the maintainer becomes a translator between competing priorities instead of building the system forward.
We've lived this internally. The previous version of Astryx supported over a million callsites and built a strong contributor community over seven years. That's real success. But the stability required to support all existing internal Meta tools meant the system couldn't evolve fast enough for teams that needed to move quickly. Product teams felt locked in, leadership found the results dated, and the distance from OSS tooling and TypeScript made it increasingly hard for AI to help. The boilerplate was heavy, the ecosystem was isolated, and importing an OSS package was never straightforward. The rewrite carries forward the conventions and institutional knowledge that scaled to a million callsites — and sheds the constraints that were holding it back.
The failure modes are on both ends of the spectrum. Too loose and the consumer bears all the cost. Too strict and the maintainer does.
We didn't start with a philosophy. We started with experiments.
Through Vibe Tests — structured evaluations of how LLMs and humans use component libraries — we tried the common industry advice: write llms.txt files, add AI-specific documentation, create detailed skills, use in-distribution libraries. Most of it either didn't work or actively made things worse.
What we found instead:
AI quality and human quality are the same thing. Every fix that improved the experience for AI also improved it for humans. The API with 30 props was confusing for both. The 10 variants where 2 covered 97% of usage were dead weight for both. The question shifted from "how do we make this AI-friendly" to "how do we make this better."
Being popular is not a prerequisite for being usable. The common theory was that libraries struggle with AI because they're out of distribution. But nobody could explain why in-distribution solutions only sometimes did well. What actually makes them work are qualities that can be built into any library: consistent conventions, standards alignment, and clear recovery paths. These are all engineerable.
The value of an internal system is its usage data, not its code. Astryx has seven years of production usage at Meta scale. The OSS rewrite ports what components are for — which props are actually used, which variants cover real cases, which patterns survive contact with production — not how they were built internally. Internal architecture reflects internal constraints that don't apply to open source.
Product building and system building need separate loops. When builders hit a gap, they can't wait for the system team. They need to unblock immediately — through swizzle, through overrides, through escape hatches. The system team consolidates those signals independently and evolves the system. Forcing everything through one loop means either the product slows down or the system gets bypassed entirely.
We stay close to the work.
Start from the builder's perspective. Every decision should be grounded in what it feels like to actually use the system. Not what sounds right in a design review, not what's theoretically elegant — what works when someone is building something real. We build with Astryx ourselves. We use it early, use it often, and let the friction we feel guide what we fix.
Test assumptions, don't debate them. When two approaches seem equally valid, we don't argue — we vibe test. Put both in front of LLMs and humans, measure what happens, and let the results decide. This has settled naming debates, prop design questions, and component structures that would otherwise be endless discussions. The data has surprised us more than once.
Hold principles loosely. We've accumulated conventions from hundreds of experiments and reviews. They steer new work in a consistent direction. But they're not rules — they're the best answers we have so far. When a new situation reveals a principle is wrong or incomplete, we update it. Consistency matters, but not more than getting it right.
Give product teams room to explore. The system shouldn't be a gate. When builders hit a gap or want to try something the system doesn't support yet, they should be able to move freely — swizzle, override, fork if they need to. Those explorations are signal, not violations. The system consolidates what works and evolves. Locking things down to protect consistency kills the feedback that makes the system better.
Dogfood relentlessly. Astryx is built with Astryx. The CLI, the documentation, the vibe test reports, the internal tools — all of it runs on the same components we ship. When something is painful for us, it's painful for everyone. We fix it because we feel it, not because someone filed a ticket.
Turn feedback into system signal. Every code review, every builder friction point, every swizzle is information. We extract that feedback — automatically where we can — and feed it back into the system. Gap reports surface what's missing. Review patterns accumulate into conventions that make the next review faster. The system learns from its own usage, not just from deliberate design sessions.
High-quality, performant, modern, open-source-compatible, well-curated component library. 90+ components, consistent conventions, typed APIs, pre-compiled CSS with zero build requirements. Our components are curated and vetted even if AI assisted in it's development. We don't ship slop. These components are intended to form the foundations of many production-ready products and we guarantee the quality through our expertise.
The pre-compiled CSS distribution means consumers don't need StyleX or any build tooling — just import the CSS. @layer ordering gives the system predictable cascade control while letting consumer styles always win. This directly addresses the styling lock-in and build friction problems.
Structured evaluations that drive API decisions. The steering mechanism that facilitates learning, surfaces novel ideas, and keeps things honest as the landscape changes.
Vibe testing is how we know our fixes work — not because we think they should, but because we measured it. It's also the guarantee that AI stays a first-class concern. The only way to truly understand how to interact with AI as a system is to do experimentation, and to do it often.
Components are fully themeable and composable across surfaces with their own visual identities — without forking or wrapping. Themes compile to static CSS. Swizzle lets you eject component source when you need to go deeper, and that ejection becomes a signal back to the system about what's missing.
Theme configuration is something a designer can own. Developers focus on building product — functionality and behaviors. Designers focus on visuals, setting up the system following best design system practices. The boundary between code and design becomes the theme, not the component source. This addresses the designer-developer friction that plagues other systems, where adopting a component library means designers lose control of the visual language.
This is the answer to both "everything looks the same" and "customization is a nightmare." Deep customization is possible, but the system tracks what you changed and why.
The CLI is the operational interface for the entire system — and the most scalable documentation driver we've found, more effective than long docs, more reliable than web-based retrieval.
It also unlocks capabilities other design systems don't have: swizzle for ejecting component source, gap reports for turning missing capabilities into actionable signals, theme building for compiling themes to static CSS, and upgrade paths for distributing codemods so breaking changes come with automated migration.
The system team itself runs with AI. Automated repo stewardship, vibe test runs, PR review, documentation audits, component research — all AI-assisted workflows. As the community grows, this extends to helping contributors navigate the spec protocol, understand conventions, and land quality PRs.
- System-Architecture — Technical architecture
- Vibe-Tests — Evaluation methodology and results
- Why-StyleX — Internal styling decision
- Contributing-with-AI-Assistants — How these principles apply to contributions
- Component Lifecycle — The specification, build, and hardening protocols
- API-Conventions — Naming and prop conventions that emerged from vibe testing