An open source design system that's fully customizable and agent ready
TypeScript
docs: correct guidance-file drift against main (#4873)
Cindy Zhange9fc2bbd653a
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.mdindex 9eb396b8c2..748baf7e90 100644--- a/.github/copilot-instructions.md+++ b/.github/copilot-instructions.md@@ -42,8 +42,11 @@ until they merge to `main`.ones.- **Semantic tokens only.** No hardcoded color, spacing, radius, or shadowvalues; components stay theme-agnostic.-- **TypeScript strict**, functional components with `forwardRef`, exported prop- types alongside the component, and a set `displayName`.+- **TypeScript strict**, functional components that declare `ref` as a prop+ (React 19 — `forwardRef` is rejected by `@eslint-react/no-forward-ref`, and+ `@astryx/require-ref-prop` requires `ref?: React.Ref<T>` on a publicly+ exported props interface), exported prop types alongside the component, and a+ set `displayName`.- **Changesets.** Consumer-visible changes need a changeset (`pnpmchangeset:new`) with a `[category]` first line and a `@handle` contributorline. Pre-1.0 bumps are `patch`, except `[breaking]`, which is `minor`.@@ -124,7 +127,9 @@ fix is an open question — state the block, then ask about the approach.match the required format (`@astryx/i18n-key-format`).- **Public API-convention violations** (see [API Conventions](https://github.com/facebook/astryx/wiki/API-Conventions)) —booleans not `is`/`has`-prefixed, wrong callback shape (`onValueChange` for the- primary change instead of `onChange`; missing `onChangeAction` async pattern),+ primary change instead of `onChange`; missing the `changeAction` async twin —+ the shipped convention is `<verb>Action` (`changeAction`, `clickAction`),+ not `on<Verb>Action`),inventing a name when a sibling convention exists (match `showOn`, `endContent`,etc.), dropping `...rest` / passthrough, or `xstyle`/`className`/`style`overwritten instead of merged via `mergeProps`. Public API shape is hard todiff --git a/.github/instructions/packages.instructions.md b/.github/instructions/packages.instructions.mdindex dc0acd0d37..58f1813f99 100644--- a/.github/instructions/packages.instructions.md+++ b/.github/instructions/packages.instructions.md@@ -429,10 +429,20 @@ and the Design review section above), or to add `hidden: true` until it does.## Mechanical checklist- **Full component surface.** A component under `packages/*/src/<Name>/` should- ship `<Name>.tsx`, a colocated `<Name>.test.tsx`, `<Name>.doc.mjs`, a- Storybook story, and an `index.ts` export. Flag missing pieces.-- **`forwardRef` + `displayName`**, `export interface <Name>Props`, and exported- types alongside the component.+ ship `<Name>.tsx`, a colocated `<Name>.test.tsx`, `<Name>.doc.mjs`, and an+ `index.ts` export, plus a Storybook story at+ `apps/storybook/stories/<Name>.stories.tsx` (stories are not colocated —+ `apps/storybook/.storybook/main.ts` only discovers+ `../stories/**/*.stories.@(js|jsx|mjs|ts|tsx)`). Flag missing pieces.+- **`ref` declared as a prop + `displayName`**, `export interface <Name>Props`,+ and exported types alongside the component. React 19 ref-as-prop is the+ convention: `forwardRef` is rejected by `@eslint-react/no-forward-ref`, and+ `@astryx/require-ref-prop` requires `ref?: React.Ref<T>` on a publicly+ exported props interface.+- **`'use client'` first.** A file that imports a React client API from `react`+ must have `'use client';` as its first statement (only comments and blank+ lines may precede it) — enforced by `pnpm check:use-client`, part of+ `pnpm check:repo`.- **Never hand-edit the `"exports"` field in a package `package.json`.** It isauto-generated from `src/` by `scripts/sync-exports.js` and committed on`main`. Editing it by hand is a review-reject.diff --git a/.github/instructions/templates.instructions.md b/.github/instructions/templates.instructions.mdindex 6a2ffe4676..637e3bc0a3 100644--- a/.github/instructions/templates.instructions.md+++ b/.github/instructions/templates.instructions.md@@ -11,7 +11,7 @@ These are Astryx **templates** — page templates (`templates/pages/<name>/page.responsibility beyond any single component.> **Scope note.** These files also match `packages.instructions.md`. For-> template files, the component-authoring checklist there (forwardRef,+> template files, the component-authoring checklist there (the `ref` prop,> sync-exports, colocated `.test.tsx`, etc.) does **not** apply — templates are> examples, not published components. Review them by the rubric below (and the> shared design and StyleX rules).diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 205feb5699..ae8a02a2f7 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -123,7 +123,7 @@ pnpm devStorybook will open at http://localhost:6006 with:-- **Theme switcher** - Toggle between Default and Shadcn themes+- **Theme switcher** - Toggle between the base tokens and the Neutral, Stone, and Y2K themes- **Mode switcher** - Toggle between Light and Dark modes- **Component stories** - Interactive component examples@@ -165,13 +165,14 @@ playground scope) before booting Next.astryx/├── apps/│ ├── storybook/ # Component playground (localhost:6006)+│ ├── docsite/ # Doc site (localhost:3000)│ └── sandbox/ # Development testing│├── packages/│ ├── core/ # Core components (Button, Input, etc.)│ ├── cli/ # CLI tooling (astryx)│ ├── lab/ # Experimental components (not yet stable)-│ └── themes/ # Theme presets (default, neutral, daily, and more)+│ └── themes/ # Theme presets (neutral, stone, y2k, and more)│└── internal/ # Internal tooling (not published)└── test-utils/ # Shared test helpers@@ -181,15 +182,15 @@ astryx/### Common Commands-| Command | Description |-| ----------------- | --------------------------------- |-| `pnpm install` | Install all dependencies |-| `pnpm dev` | Start all dev servers |-| `pnpm build` | Build all packages |-| `pnpm test` | Run all tests |-| `pnpm test:watch` | Run tests in watch mode |-| `pnpm storybook` | Start Storybook at localhost:6006 |-| `pnpm lint` | Lint all packages |+| Command | Description |+| ----------------- | -------------------------------------------- |+| `pnpm install` | Install all dependencies |+| `pnpm dev` | Start Storybook (alias for `pnpm storybook`) |+| `pnpm build` | Build all packages |+| `pnpm test` | Run all tests |+| `pnpm test:watch` | Run tests in watch mode |+| `pnpm storybook` | Start Storybook at localhost:6006 |+| `pnpm lint` | Lint all packages |## Adding a New Component@@ -207,17 +208,25 @@ mkdir -p packages/core/src/MyComponentpackages/core/src/MyComponent/├── MyComponent.tsx # Component implementation├── MyComponent.test.tsx # Unit tests (colocated)-├── MyComponent.stories.tsx # Storybook stories+├── MyComponent.doc.mjs # Component doc (props, features, examples)└── index.ts # Public exports```+Stories are **not** colocated — they live in the Storybook app:++```+apps/storybook/stories/MyComponent.stories.tsx+```+### 3. Component Template````tsx// MyComponent.tsx-import {forwardRef, type HTMLAttributes, type ReactNode} from 'react';+import type {HTMLAttributes, ReactNode, Ref} from 'react';export interface MyComponentProps extends HTMLAttributes<HTMLDivElement> {+ /** Ref forwarded to the root element */+ ref?: Ref<HTMLDivElement>;/** Description for AI-assisted development */children: ReactNode;}@@ -230,15 +239,13 @@ export interface MyComponentProps extends HTMLAttributes<HTMLDivElement> {* <MyComponent>Hello</MyComponent>* ```*/-export const MyComponent = forwardRef<HTMLDivElement, MyComponentProps>(- ({children, ...props}, ref) => {- return (- <div ref={ref} {...props}>- {children}- </div>- );- },-);+export function MyComponent({children, ref, ...props}: MyComponentProps) {+ return (+ <div ref={ref} {...props}>+ {children}+ </div>+ );+}MyComponent.displayName = 'MyComponent';````@@ -261,13 +268,19 @@ describe('MyComponent', () => {### 5. Story Template+Stories live in the Storybook app, not next to the component —+`apps/storybook/.storybook/main.ts` discovers them with+`'../stories/**/*.stories.@(js|jsx|mjs|ts|tsx)'`, so a story anywhere under+`packages/` is never picked up. Import the component through its published+entry point, and title it under `Core/` (or `Lab/` for `@astryxdesign/lab`).+```tsx-// MyComponent.stories.tsx+// apps/storybook/stories/MyComponent.stories.tsximport type {Meta, StoryObj} from '@storybook/react';-import {MyComponent} from './MyComponent';+import {MyComponent} from '@astryxdesign/core/MyComponent';const meta = {- title: 'Components/MyComponent',+ title: 'Core/MyComponent',component: MyComponent,tags: ['autodocs'],} satisfies Meta<typeof MyComponent>;@@ -353,7 +366,7 @@ Most of the conventions above are mechanical, so they're checked rather than rev| each `api/<name>/` ships its typedefs, a `FunctionDoc`, and a test | `pnpm check:cli-structure` || every `CommandDoc`/`EnumDoc` matches the live CLI | the drift harness |-You never hand-write the `.d.mts` declarations. `scripts/sync-api-types.mjs` emits them for both `api/` and `authoring/` from the `.mjs` JSDoc — gitignored, regenerated at `prepack`, and stamped `@generated`. Edit the JSDoc and run `pnpm -F @astryxdesign/cli sync:api-types`.+You never hand-write the `.d.mts` declarations. `packages/cli/scripts/sync-api-types.mjs` emits them for both `api/` and `authoring/` from the `.mjs` JSDoc — gitignored, regenerated at `prepack`, and stamped `@generated`. Edit the JSDoc and run `pnpm -F @astryxdesign/cli sync:api-types`.That matters because a hand-written declaration _shadows_ the JSDoc in its `.mjs`, and both ways it can lie shipped once: a missing declaration made a strict consumer resolve the parser as `any` (surfacing only at pack time as TS7016, since local typechecks run with `checkJs` and never exercise the packed surface), and a stale `parseDoc` union silently dropped three doc kinds from the published type while still compiling. Generation removes both. The one declaration still written by hand is `authoring/index.d.ts`, the curated public barrel.@@ -403,8 +416,9 @@ pnpm -F @astryxdesign/core test# With coveragepnpm test:coverage-# Screenshot tests-pnpm test:screenshots+# Accessibility and RTL audits over the built Storybook (see below)+pnpm a11y:audit+pnpm rtl:audit```### Test Structure@@ -550,7 +564,10 @@ yet" — open the PR as a draft and mark it ready for review when it's done.## Code Style- TypeScript strict mode-- Functional components with `forwardRef`+- Functional components that declare `ref` as a prop (React 19 — no+ `forwardRef`; `@eslint-react/no-forward-ref` rejects it, and+ `@astryx/require-ref-prop` requires `ref?: React.Ref<T>` on a publicly+ exported props interface)- JSDoc comments for AI-assisted development- Export types alongside componentsdiff --git a/package.json b/package.jsonindex 7a1e799356..ebdfd6a79a 100644--- a/package.json+++ b/package.json@@ -11,12 +11,13 @@"test:watch": "vitest","test:coverage": "vitest --coverage","check:package-boundaries": "node scripts/check-package-boundaries.js",- "check:repo": "pnpm check:sync && pnpm check:package-boundaries && pnpm check:changesets && pnpm check:demo-media && pnpm check:executable-bits && pnpm check:cli-structure",+ "check:repo": "pnpm check:sync && pnpm check:package-boundaries && pnpm check:changesets && pnpm check:demo-media && pnpm check:executable-bits && pnpm check:cli-structure && pnpm check:use-client","check:changesets": "node scripts/check-changesets.mjs","check:cli-structure": "node scripts/check-cli-structure.mjs","check:executable-bits": "node scripts/check-executable-bits.mjs","check:demo-media": "node scripts/check-demo-media.mjs","check:sync": "node scripts/check-sync.js",+ "check:use-client": "node scripts/check-use-client.mjs","lint": "pnpm check:repo && eslint . --cache","lint:strict": "pnpm check:repo && ASTRYX_STRICT_LINT=1 eslint . --cache","a11y:audit": "node .github/scripts/accessibility-audit.js --baseline .github/a11y-baseline.json --fail-on-new",