Silk

@reactive/silk — a long-lived design system foundation for React (web) with a path toward shared concepts on React Native / Expo.

This is not another Tailwind/shadcn component dump. Silk owns its API, uses Radix for behavior, Linaria for statically extracted CSS, and themes through semantic tokens + CSS variables.

Documentation

Primary docs site: Storybook on GitHub Pages (tracks main).

Locally:

yarn build   # silk-core dist required for Linaria
yarn docs    # http://localhost:6006

Status

Stage 6 (@reactive/silk-native): React Native renderer for the same Theme object and recipes (Box / Stack / Inline / Text / Button), Expo example app, RNW Storybook stories + NativeShell fixture. Prior stages shipped theming maturity, layout, visual/forms, interaction primitives, and composites. The staged plan is in docs/ROADMAP.md; the project charter is docs/PRINCIPLES.md.

Packages

Package	Description
@reactive/silk-core	Platform-neutral tokens, createTheme, recipe contracts
@reactive/silk	Web design system (Radix + Linaria)
@reactive/silk-native	React Native renderer (context themes, no CSS variables)

Apps

App	Description
@reactive/silk-docs	Private Storybook docs site (not published)
@reactive/silk-native-example	Expo example consuming @reactive/silk-native (not published)

Libraries live under packages/; runnable consumers (docs, native examples) live under apps/.

Requirements

• Node.js 22+
• Yarn 4 via Corepack

Development

corepack enable
yarn install
yarn build
yarn typecheck
yarn test

silk-core must build before silk (package exports and Linaria both resolve core from dist/). Topological yarn workspaces foreach -A -pt handles this — run yarn build before yarn typecheck on a clean checkout.

Scripts

Script	Description
yarn build	Build publishable workspaces
yarn typecheck	Typecheck all workspaces
yarn test	Run tests
yarn docs	Start Storybook docs site
yarn docs:build	Build static Storybook (apps/docs/storybook-static)
yarn changeset	Add a changeset for the next release
yarn release	Build and publish (used by CI)

Quick start

import {
  Button,
  Identity,
  SilkProvider,
  createTheme,
} from '@reactive/silk';
import '@reactive/silk/styles.css';
// Optional — Silk ships no font files (see docs Theming → Typography and fonts).
import '@fontsource-variable/inter';
import '@fontsource-variable/source-serif-4';
import '@fontsource-variable/jetbrains-mono';

export function App() {
  return (
    <SilkProvider colorScheme="light" defaults={{ Button: { variant: 'soft' } }}>
      <Button tone="accent">Save</Button>
      <Identity name="Ada Lovelace" meta="@ada" fallback="AL" />
    </SilkProvider>
  );
}

Custom / tenant themes use the style-attribute path. For brand seeds with paired light/dark:

import { createTheme, generatePairedPalette } from '@reactive/silk';

const paired = generatePairedPalette('#0ea5e9');
<SilkProvider theme={createTheme({ colorScheme: 'light', palette: paired.light })}>
  …
</SilkProvider>

@reactive/silk/styles.layer.css ships the same rules wrapped in @layer silk, so unlayered consumer CSS overrides Silk deterministically instead of depending on stylesheet order. Opt in when you control your own reset — see the cascade-order section in docs/ARCHITECTURE.md.

Architecture

Component usage and theming live in Storybook. The repository architecture write-up is docs/ARCHITECTURE.md, the guiding principles are docs/PRINCIPLES.md, and the staged plan is docs/ROADMAP.md.

design-tokens
      ↓
semantic theme
      ↓
component recipes/contracts
      ↓
platform renderer (web: Radix + Linaria · native: React Native)

Hard constraints: no Tailwind, no CVA, CSS-first (Linaria), SSR-first (Anansi), accessibility via Radix.

Registry

Composites can also be installed as source via the shadcn registry protocol. See root registry.json. Items will pin compatible @reactive/silk versions once published from release tags (the scaffold is unpinned pre-release); zero Tailwind.

Validate:

npx shadcn@latest registry validate

TypeScript 7

This project uses TypeScript 7 (native Go compiler via the typescript package). If declaration generation hits an edge case with the native compiler, the fallback is installing @typescript/typescript6 for the dts step only — do not pre-install it unless needed.

License

MIT