Architecture decisions, roadmap, and vision for stoked-ds. This document provides transparency into where the project is, where it's going, and the principles that guide every decision.
Every decision in stoked-ds is guided by these core principles. They define what we build, how we build it, and what we deliberately choose not to do.
CSS Modules with CSS Variables. No JavaScript overhead at runtime. Theme switching happens instantly through CSS cascade, not re-renders.
We don't build inferior versions of TanStack Table or react-day-picker. We wrap the best libraries with our tokens and styling. The ecosystem wins.
WAI-ARIA patterns, keyboard navigation, focus management, and screen reader support. Every component, every release. No exceptions.
Only 1 production dependency (clsx). All animations are pure CSS. Everything else is a peer or dev dependency. Your bundle stays lean.
Trusted Publishers with OIDC, provenance attestation, CycloneDX SBOM, npm audit in CI. Every release is cryptographically verifiable.
Every component ships with unit tests, Storybook stories, and TypeScript types. 1:1 test-to-component ratio. No undocumented features.
A summary of the key architectural decisions that make stoked-ds different from other React design systems.
Data-attribute variants instead of CSS classes. Variants are visible in DevTools as data-variant="solid", selectors are self-documenting, and there's no className collision. Each component controls its own attribute namespace.
Component-level CSS variables create a clean layering system: global tokens cascade into component defaults, which are overridden by variant selectors. No specificity wars, no !important.
Sub-path exports keep integrations isolated. Each adapter has its own entry point (stoked-ds/integrations/tanstack-table), its own bundle, and its external library as an optional peer dependency. The core bundle is never affected by integration code.
ESM-only output with 95 separate entry files maximizes tree-shaking. Import one component, only that component's code and CSS end up in your bundle. CSS is declared as a side effect for proper inclusion.
Pure CSS animation strategy: All animations use CSS keyframes and transitions defined in component CSS modules. Mount/unmount transitions (Modal, Toast) are managed by a lightweight useExitAnimation hook with data-state attributes. All motion respects prefers-reduced-motion via CSS media queries.
A phased plan designed for predictability. Each phase builds on the previous one, with clear deliverables and priorities.
Core component library, design token system, integrations, and documentation. The foundation everything else builds on.
Security pipeline, SEO optimization, architecture documentation, and community building. Making the project trustworthy and discoverable.
New components that developers frequently need but rarely find well-implemented. Each one fills a gap in the current catalog.
Unstyled component primitives that provide behavior, accessibility, and keyboard navigation without any CSS. Full customization power.
Enterprise-grade integrations with popular commercial and open-source libraries. Open core model with premium adapters.
AI-powered tooling, design-to-code pipeline, stable API commitment, and enterprise patterns. The full ecosystem play.
Every release is cryptographically verifiable. We don't just build components — we build trust.
Trusted Publishers with OIDC — No npm tokens stored in CI. GitHub Actions receives ephemeral tokens per workflow run via OpenID Connect. Tokens expire immediately after use.
Provenance attestation — Every published version includes a signed attestation linking the package to the exact commit, workflow run, and repository. Verify with npm audit signatures.
CycloneDX SBOM — A Software Bill of Materials is generated for every release and attached as a GitHub Release asset. Full transparency into what ships in the package.
Automated dependency monitoring — Dependabot creates grouped PRs weekly. npm audit runs on every pull request, blocking merges on high/critical vulnerabilities in production dependencies.
Package validation — Before every publish, the tarball is scanned for sensitive files (.env, credentials, keys). The files allowlist in package.json ensures only dist/, README, LICENSE, and CHANGELOG are included.
Install stoked-ds and start shipping accessible, performant interfaces today.