@alfadocs/ui-kit 0.0.12 → 0.0.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +74 -138
  2. package/dist/agent-catalog.json +1 -1
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,152 +1,88 @@
1
1
  # @alfadocs/ui-kit
2
2
 
3
- The AlfaDocs shared design system — a single source of truth for tokens, components, patterns, and translations across platform, booking, and alfascribe.
3
+ The AlfaDocs design system — React components, tokens, and translations.
4
4
 
5
- **Status:** 0.0.1 (pre-release, iterating)
6
- **Repo:** `alfadocs/design_system`
7
- **Package:** `@alfadocs/ui-kit` (published to GitHub Packages, `npm.pkg.github.com`)
8
- **Visual reference:** https://new-alfa-docs.vercel.app/ (saved locally in [`reference/vercel-reference.html`](./reference/vercel-reference.html))
5
+ > **Pre-release.** APIs may change between minor versions before 1.0.
9
6
 
10
- Authoritative contributor guide: [`CLAUDE.md`](./CLAUDE.md). The product requirements specification lives at [`src/docs/`](./src/docs/) and is also rendered inside Storybook.
7
+ ## Install
11
8
 
12
- ## Stack
9
+ ```bash
10
+ npm install @alfadocs/ui-kit
11
+ ```
12
+
13
+ Requires React 18+ and Node ≥ 22.6.
13
14
 
14
- | Layer | Technology |
15
- |---|---|
16
- | Language | React 18 + TypeScript (strict) |
17
- | Component foundation | shadcn/ui + Radix UI primitives |
18
- | Styling | Tailwind CSS v4 + CVA (class-variance-authority), tokens in `src/tokens/index.css` |
19
- | Build | Vite (library mode) |
20
- | Documentation | Storybook 10 (`@storybook/react-vite`) |
21
- | Testing | Vitest + Playwright (browser mode) via `@storybook/addon-vitest` + axe-core |
22
- | i18n | `react-i18next` (18 locales, RTL for `ar`) |
15
+ ## Usage
23
16
 
24
- ## Repo layout
17
+ ### Tokens
25
18
 
19
+ Import the design tokens once at your app root so the CSS custom
20
+ properties are available everywhere:
21
+
22
+ ```ts
23
+ import '@alfadocs/ui-kit/tokens';
26
24
  ```
27
- design_system/
28
- ├── .claude/ agents & skills shared with the team
29
- ├── .storybook/ framework, decorators, theme/locale switchers
30
- ├── reference/ brand PDFs, Vercel marketing HTML (read-only)
31
- ├── scripts/ build-locales.mjs etc.
32
- ├── templates/ component-docs.mdx.template, pattern-docs.mdx.template
33
- └── src/
34
- ├── tokens/
35
- │ ├── index.css single source of truth for CSS custom properties
36
- │ ├── ag-grid-theme.css
37
- │ ├── apexcharts-theme.ts
38
- │ └── themes/bridges/ fullcalendar, react-day-picker, tiptap, stripe
39
- ├── brand/ colour tables, type specimens, logo assets, *.mdx
40
- ├── components/ 95 components, each with .tsx / .stories.tsx / .test.tsx / .mdx
41
- ├── patterns/ composition layer — realistic AlfaDocs workflows
42
- ├── hooks/ use-prefers-reduced-motion, …
43
- ├── i18n/ config.ts + resources.ts (bundled locales)
44
- ├── docs/ PRS §§ 01–25 + examples/
45
- └── user_stories/ foundations + feature stories (done/ and to-do/)
25
+
26
+ Then apply a theme class on the root element:
27
+
28
+ ```html
29
+ <html class="theme-light">
30
+ <!-- or theme-dark, optionally combined with theme-accessible -->
31
+ </html>
46
32
  ```
47
33
 
48
- ## Getting started
34
+ ### Components
49
35
 
50
- ```bash
51
- npm install
52
- npm run storybook # Storybook on port 6006 — browse components, patterns, PRS
36
+ Each component is also available as its own subpath import for
37
+ narrower bundles:
38
+
39
+ ```tsx
40
+ import { Button } from '@alfadocs/ui-kit/button';
41
+ import { Card } from '@alfadocs/ui-kit/card';
42
+
43
+ export function Example() {
44
+ return (
45
+ <Card>
46
+ <Card.Body>
47
+ <Button intent="primary">Save</Button>
48
+ </Card.Body>
49
+ </Card>
50
+ );
51
+ }
53
52
  ```
54
53
 
55
- | Script | What it does |
56
- |---|---|
57
- | `npm run dev` | Vite dev server |
58
- | `npm run storybook` | Storybook on port 6006 |
59
- | `npm run build` | `tsc --noEmit` → `vite build` → `build:types` → `build:locales` |
60
- | `npm run build:types` | Emit `.d.ts` via `tsconfig.build.json` |
61
- | `npm run build:locales` | Copy locale JSON into `dist/locales/` |
62
- | `npm run build-storybook` | Static Storybook into `storybook-static/` |
63
- | `npx vitest` / `npx vitest run` | Vitest (browser mode) for story tests |
64
-
65
- Node ≥ 22.6.0 is required (`engines.node`).
66
-
67
- ## Package exports
68
-
69
- Consumers install `@alfadocs/ui-kit` from the GitHub Packages registry and import from these entry points:
70
-
71
- | Export | Purpose |
72
- |---|---|
73
- | `@alfadocs/ui-kit` | React components (the default entry) |
74
- | `@alfadocs/ui-kit/tokens` | `tokens.css` — CSS custom properties (import once at app root) |
75
- | `@alfadocs/ui-kit/i18n` | Pre-configured `i18next` instance |
76
- | `@alfadocs/ui-kit/locales/*` | Locale JSON bundles (e.g. `.../locales/en.json`) |
77
-
78
- See [`src/docs/25-consuming.mdx`](./src/docs/25-consuming.mdx) for integration recipes.
79
-
80
- ## Product Requirements Specification
81
-
82
- All sections live as MDX under [`src/docs/`](./src/docs/) and render in Storybook under **Product Requirements Specification → Documentation**.
83
-
84
- ### Foundations
85
- - [01 — Overview & Goals](./src/docs/01-overview.mdx)
86
- - [02 — Current State](./src/docs/02-current-state.mdx)
87
- - [03 — Architecture](./src/docs/03-architecture.mdx)
88
- - [04 — Theming](./src/docs/04-theming.mdx)
89
- - [05 — Accessibility](./src/docs/05-accessibility.mdx)
90
- - [06 — Internationalisation](./src/docs/06-i18n.mdx)
91
-
92
- ### Library
93
- - [07 — Component Library](./src/docs/07-component-library.mdx)
94
- - [08 — Third-Party Library Stack](./src/docs/08-third-party.mdx)
95
- - [09 — Centralisation Strategy](./src/docs/09-centralisation.mdx)
96
-
97
- ### Design & docs
98
- - [11 — Storybook](./src/docs/11-storybook.mdx)
99
-
100
- ### Non-functional
101
- - [12 — Security](./src/docs/12-security.mdx)
102
- - [13 — Maintainability](./src/docs/13-maintainability.mdx)
103
- - [14 — Browser & Device Compatibility](./src/docs/14-browser-compat.mdx)
104
- - [15 — Responsive Design & Breakpoints](./src/docs/15-responsive.mdx)
105
- - [16 — Print Styles & PDF Generation](./src/docs/16-print.mdx)
106
- - [17 — Error Handling & Resilience](./src/docs/17-error-handling.mdx)
107
- - [18 — Animation & Motion Tokens](./src/docs/18-animation.mdx)
108
- - [19 — Performance Requirements](./src/docs/19-performance.mdx)
109
-
110
- ### Process
111
- - [20 — Versioning & Release Strategy](./src/docs/20-versioning.mdx)
112
- - [21 — Contribution Guidelines & Governance](./src/docs/21-contribution.mdx)
113
- - [22 — Agent Instructions](./src/docs/22-agents.mdx)
114
- - [23 — Mandatory Constraints](./src/docs/23-constraints.mdx)
115
- - [24 — Experimentation](./src/docs/24-experimentation.mdx)
116
- - [25 — Consuming the Kit](./src/docs/25-consuming.mdx)
117
-
118
- ## Hard constraints
119
-
120
- The full list is in [`src/docs/23-constraints.mdx`](./src/docs/23-constraints.mdx). Highlights CI enforces:
121
-
122
- - Tokens only — no hardcoded colours, spacing, radii, shadows, fonts in components
123
- - CSS logical properties only — `ms-*`/`me-*`/`ps-*`/`pe-*`, never `ml-*`/`mr-*`/`pl-*`/`pr-*`
124
- - No inline `style={{…}}`; Tailwind classes only
125
- - All user-visible strings routed through `useTranslation()`; `ui.*` namespace for kit, `app.*` for consumers
126
- - axe-core zero violations per story
127
- - TypeScript strict, no `any`, no PropTypes, `forwardRef` where a ref is exposed
128
- - No `dangerouslySetInnerHTML` outside the `SafeHtml` helper
129
- - No jQuery (and no library that depends on it)
130
- - CVA for every component's variants
131
- - Co-located `.stories.tsx` and `.test.tsx` for every component
132
- - Four themes compose through class names on the theme root: `theme-light`, `theme-dark`, each optionally with `theme-accessible` (AAA)
133
-
134
- ## Agents & skills
135
-
136
- Project-scoped agents (`.claude/agents/`) and user-invocable skills (`.claude/skills/`) are tracked in git. See [`CLAUDE.md`](./CLAUDE.md#agents--skills) for the full catalogue; common entry points:
137
-
138
- | Invocation | Purpose |
139
- |---|---|
140
- | `/new-component <Name> [category]` | scaffold a new component and self-check it |
141
- | `/component-gate <component-path>` | verify one component against the 9-row acceptance gate |
142
- | `/ds-check [path-or-diff]` | run `token-auditor` + `a11y-reviewer` in parallel and merge findings |
143
-
144
- Every feature implementation runs through `code-reviewer`, `a11y-reviewer`, and `token-auditor` in parallel before being declared done — see the "Post-implementation review" section in `CLAUDE.md`.
145
-
146
- ## Environment variables
147
-
148
- Non-secret build-time values live in `.env` at the repo root and are read by Vite (and therefore Storybook). Anything genuinely secret goes in `.env.local` (gitignored).
149
-
150
- | Variable | Committed? | Purpose |
151
- |---|---|---|
152
- | `VITE_FULLCALENDAR_LICENSE_KEY` | ✔ `.env` | Scheduler premium key for `resourceTimeline` in `Calendar`. Domain-bound, ships in the client bundle, not a cryptographic secret. Without it, FullCalendar renders an "invalid license" watermark. |
54
+ Or import everything from the root entry:
55
+
56
+ ```tsx
57
+ import { Button, Card } from '@alfadocs/ui-kit';
58
+ ```
59
+
60
+ ### i18n
61
+
62
+ The kit ships with `react-i18next` pre-configured and locale bundles
63
+ in `dist/locales/`:
64
+
65
+ ```ts
66
+ import i18n from '@alfadocs/ui-kit/i18n';
67
+ import en from '@alfadocs/ui-kit/locales/en.json';
68
+
69
+ i18n.addResourceBundle('en', 'ui', en);
70
+ ```
71
+
72
+ ## Peer dependencies
73
+
74
+ `react`, `react-dom`, `react-i18next`, `i18next`. Tailwind CSS is not
75
+ required to consume the kit — components ship pre-styled, and the
76
+ tokens stylesheet exposes CSS custom properties you can reference from
77
+ your own styles.
78
+
79
+ ## License
80
+
81
+ [Business Source License 1.1](./LICENSE) — production use is
82
+ permitted; offering the Licensed Work, or a substantial portion of it,
83
+ as a competing hosted, embedded, or rebranded design-system or
84
+ component-library product is not. The Licensed Work converts to the
85
+ Apache License 2.0 on the Change Date specified in the LICENSE.
86
+
87
+ For commercial licensing arrangements outside the BUSL grant, contact
88
+ AlfaDocs GmbH.
package/dist/agent-catalog.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
- "packageVersion": "0.0.12",
3
+ "packageVersion": "0.0.13",
4
4
  "components": [
5
5
  {
6
6
  "kind": "component",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@alfadocs/ui-kit",
3
- "version": "0.0.12",
3
+ "version": "0.0.13",
4
4
  "type": "module",
5
5
  "description": "AlfaDocs shared design system — tokens, components, patterns, and translations for platform, booking, and alfascribe.",
6
6
  "license": "BUSL-1.1",