@yanolja-next/design-core 0.0.0-stage → 0.1.0

package/AGENTS.md

@@ -0,0 +1,37 @@
+# Instructions for AI agents
+
+This package (`@yanolja-next/design-core`) holds the product-neutral parts of the Yanolja NEXT design system. Follow these steps when you build or change a React screen in a product that uses it.
+
+## Before you write a screen
+
+1. Read `catalog.json` in this package. If the package is not installed, install it first (see `README.md`). If the repository is next-hub, read `design-system/core/src/catalog.ts` in the workspace instead. When the two differ, the installed package is correct for that product.
+2. Write in one line what the screen part must do. Find the entry whose `intent` and `use` match that line.
+3. If the entry's `avoid` matches your case, go to an entry in `instead`.
+4. Read the rule that the entry names (`rule`, E.g., `P6`) in `RULES.md`.
+5. Read the props of the part in `dist/index.d.ts`. In the next-hub workspace, `dist` exists only after a build. Read the part source in `design-system/core/src/components` instead.
+
+## App setup
+
+Before the first screen, check the app setup in `README.md`: the CSS imports, `setLocale` for an English app, `LinkProvider` for a router app, `ToastProvider`, the sign-out route, the page path in the top bar and the jsdom test stubs.
+
+## Screen CSS holds layout only
+
+- Screen CSS holds page layout only: grids, column widths, spacing between sections and one-off positions.
+- Do not build a part in screen CSS. A part is anything with its own look or behavior: a box, a text style, a state, a hover or press, or a keyboard pattern.
+- Do not write raw colours, font sizes, radii or durations. Use the token variables (`var(--c-text)`, `var(--t-13)`) or a part.
+
+## When no part fits
+
+1. Build the part in the product's own kit, with a catalog entry (intent, use, avoid, instead). Do not build it in screen CSS.
+2. Design the part by its intent. Its props name what varies inside that intent, such as tone, size or state. Do not add a flag that copies one screen's CSS.
+3. If another product already has a kit part with the same intent, open an issue or a next-hub pull request to move the part to core. A part moves to core when a second product needs it, and the move removes product words from its catalog entry and its props.
+
+## Themes
+
+Do not add or change a theme by yourself. A theme is a design decision. Ask the user which semantic values must change.
+
+## Do not
+
+- Do not import from a path inside the package (`@yanolja-next/design-core/dist/...`). Import from the package name.
+- Do not copy a part into the product to change its look. Extend the part, or ask for a new part.
+- Do not use this package with React 18. Stop and tell the user.

package/README.md

@@ -1,3 +1,147 @@
-# Temporary Holding Version
+# @yanolja-next/design-core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Product-neutral React parts of the Yanolja NEXT design system, with their prebuilt CSS.
+The values (colours, sizes, motion, fonts) come from `@yanolja-next/design-tokens`.
+
+## Install
+
+```sh
+pnpm add @yanolja-next/design-tokens @yanolja-next/design-core pretendard
+```
+
+The parts need React 19 (`react` and `react-dom` are peer dependencies).
+
+## CSS
+
+Import the fonts and the prebuilt CSS once, at the app entry:
+
+```ts
+import 'pretendard/dist/web/variable/pretendardvariable-dynamic-subset.css';
+import '@yanolja-next/design-tokens/fonts.css';
+import '@yanolja-next/design-core/styles.css';
+```
+
+- `styles.css` holds the token variables, the Tailwind utilities that the parts use and the base rules. The app does not need Tailwind.
+- All layered rules sit under the cascade layer `ds` (`ds.theme`, `ds.base`, `ds.components`, `ds.utilities`). Your unlayered CSS wins over them. A layer you declare before `ds` loses to them (see the Tailwind notes below).
+- An app that runs Tailwind can add `@yanolja-next/design-tokens/tailwind.css` to its own Tailwind entry. Then classes such as `bg-panel` and `text-13` read the same tokens.
+- For visually hidden text (a label that only screen readers read), use the `sr-only` class. `styles.css` ships it, so an app without Tailwind can use it too.
+
+### Tailwind apps: put your layers before `ds`
+
+Your utilities and the part utilities share names (`grid`, `flex`, `hidden`). If your utility layer comes after `ds`, your `.grid` beats a part's responsive rule on the same element, such as `tablet:hidden`. On a phone the top bar then shows two menu buttons. Import your Tailwind entry before `@yanolja-next/design-core/styles.css`, so your layers are declared first and the parts win on their own elements.
+
+### Tailwind apps: do not add the preflight again
+
+`styles.css` already holds the Tailwind preflight in `ds.base`. Do not use `@import 'tailwindcss'` in your Tailwind entry. That import adds the preflight again in a layer after `ds`, and it removes the backgrounds and borders of the parts. Import the theme and the utilities only:
+
+```css
+@layer theme, base, components, utilities;
+@import 'tailwindcss/theme.css' layer(theme);
+@import '@yanolja-next/design-tokens/tailwind.css';
+@import 'tailwindcss/utilities.css' layer(utilities);
+
+/* The same narrow-screen variants as core */
+@custom-variant laptop (@media (max-width: 1180px));
+@custom-variant tablet (@media (max-width: 900px));
+@custom-variant phone (@media (max-width: 640px));
+```
+
+## App setup
+
+Do these steps once, at the app entry.
+
+### Language
+
+The text inside the parts is Korean by default. An English app calls `setLocale('en')` before the first render. Call it in the test setup too, or the tests see Korean text.
+
+```ts
+import { setLocale } from '@yanolja-next/design-core';
+
+setLocale('en');
+```
+
+### Router links
+
+Topbar, Sidebar, Drawer, Tabs, `TableName href`, `MetricStrip href` and other parts draw their own links. Without `LinkProvider`, they draw a plain `<a>` and each click reloads the page. Give the router link to `LinkProvider` at the top of the app:
+
+```tsx
+import { type LinkProps, LinkProvider, ToastProvider } from '@yanolja-next/design-core';
+import { Link as RouterLink } from 'react-router-dom';
+
+const Link = ({ href, ...props }: LinkProps) => <RouterLink to={href} {...props} />;
+
+<LinkProvider component={Link}>
+  <ToastProvider>
+    <App />
+  </ToastProvider>
+</LinkProvider>;
+```
+
+### Toasts
+
+`ToastProvider` draws the toasts. Inside it, a component calls `useToast().show({ title })`.
+
+Code outside a component, such as a data hook at the end of a request, calls `showToast({ title })`. It uses the mounted `ToastProvider`. When no `ToastProvider` is mounted, it does nothing.
+
+### Sign-out
+
+The account menu in Topbar has a sign-out link, not a callback. Give its address in `signOutHref` and add a route at that address that signs the user out (E.g., `/sign-out`).
+
+### Page path in the top bar
+
+`PageHead crumbs` does not draw the path in the page. It sends the path to the shell through `PagePathContext`, and Topbar draws it. `AppShell` does not do this by itself. Keep the path in state, provide the setter, and give the path to `Topbar path`:
+
+```tsx
+const [path, setPath] = useState<PagePath>();
+
+<AppShell topbar={<Topbar path={path} signOutHref="/sign-out" {...rest} />} sidebar={sidebar}>
+  <PagePathContext.Provider value={setPath}>{children}</PagePathContext.Provider>
+</AppShell>;
+```
+
+## Tests in jsdom
+
+The Radix parts (Select, Popover, Menu, Toast and others) call browser APIs that jsdom does not have, and the tests crash. Add these stubs to the test setup file:
+
+```ts
+class ResizeObserverStub {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+}
+globalThis.ResizeObserver ??= ResizeObserverStub as unknown as typeof ResizeObserver;
+Element.prototype.hasPointerCapture ??= () => false;
+Element.prototype.releasePointerCapture ??= () => {};
+Element.prototype.scrollIntoView ??= () => {};
+window.matchMedia ??= ((query: string) => ({
+  matches: query === '(prefers-reduced-motion: reduce)',
+  media: query,
+  onchange: null,
+  addListener: () => {},
+  removeListener: () => {},
+  addEventListener: () => {},
+  removeEventListener: () => {},
+  dispatchEvent: () => false,
+})) as unknown as typeof window.matchMedia;
+```
+
+The `matchMedia` stub turns on reduced motion, so counters and bars show their final value at once.
+
+Some parts behave differently from native elements in tests:
+
+- `Select` is a Radix select, not a native `<select>`. `fireEvent.change` does nothing. Open it with a click and click the option.
+- `Button loading` sets `aria-busy`, not `disabled`. Assert `aria-busy="true"`, not `toBeDisabled()`.
+
+## Theme
+
+The default theme is the light theme of the NEXT Hub console. A product theme changes only semantic values (for example `--c-accent`). Ask the design owner before you add one.
+
+## Find a part
+
+Pick a part by what you want to do, not by its name:
+
+- `catalog.json`: every part with its intent, where to use it, where not to use it, what to use instead, and the rule it follows. The package also exports it as `catalog`.
+- `RULES.md`: the screen rules (P1 to P20, L1 to L5) that the catalog names.
+- `llms.txt`: a one-screen index for AI agents.
+- `AGENTS.md`: instructions for AI agents. Point your repository `AGENTS.md` or `CLAUDE.md` at `node_modules/@yanolja-next/design-core/AGENTS.md`.
+- `dist/index.d.ts`: the props of every part. In the next-hub workspace, `dist` exists only after a build. Read the part source in `design-system/core/src/components` instead.