Skip to content

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.md
index 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 shadow
values; 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 (`pnpm
changeset:new`) with a `[category]` first line and a `@handle` contributor
line. 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 to
diff --git a/.github/instructions/packages.instructions.md b/.github/instructions/packages.instructions.md
index 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 is
auto-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.md
index 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.md
index 205feb5699..ae8a02a2f7 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -123,7 +123,7 @@ pnpm dev
Storybook 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/MyComponent
packages/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.tsx
import 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 coverage
pnpm 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 components
diff --git a/package.json b/package.json
index 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",