@persona/design-system 0.1.8 → 0.2.0

package/dist/patterns/PageLayout/index.mjs

@@ -0,0 +1,35 @@
+import { Spacing } from "@persona/design-tokens";
+import styled from "styled-components";
+import { jsx } from "react/jsx-runtime";
+//#region patterns/PageLayout/PageLayout.tsx
+const Backdrop = styled.div`
+  position: relative;
+  width: 100%;
+  padding: ${Spacing[7]} ${Spacing[5]};
+
+  display: flex;
+  flex-direction: column;
+`;
+const StyledContainer = styled("div")`
+  position: relative;
+  width: 100%;
+  padding: 0;
+
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+`;
+const Container = ({ children, ...rest }) => {
+	return /* @__PURE__ */ jsx(StyledContainer, {
+		...rest,
+		children
+	});
+};
+const Section = styled("div")`
+  width: 100%;
+  padding: ${Spacing[7]};
+`;
+//#endregion
+export { Backdrop, Container, Section };
+
+//# sourceMappingURL=index.mjs.map

package/dist/patterns/PageLayout/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../../patterns/PageLayout/PageLayout.tsx"],"sourcesContent":["import type { ComponentPropsWithoutRef, ReactNode } from 'react';\nimport styled from 'styled-components';\n\nimport { Spacing } from '@persona/design-tokens';\n\nexport const Backdrop = styled.div`\n  position: relative;\n  width: 100%;\n  padding: ${Spacing[7]} ${Spacing[5]};\n\n  display: flex;\n  flex-direction: column;\n`;\n\nconst StyledContainer = styled('div')`\n  position: relative;\n  width: 100%;\n  padding: 0;\n\n  display: flex;\n  flex-direction: column;\n  align-items: center;\n`;\n\nexport const Container = ({\n  children,\n  ...rest\n}: { children: ReactNode } & ComponentPropsWithoutRef<'div'>) => {\n  return <StyledContainer {...rest}>{children}</StyledContainer>;\n};\n\nexport const Section = styled('div')`\n  width: 100%;\n  padding: ${Spacing[7]};\n`;\n"],"mappings":";;;;AAKA,MAAa,WAAW,OAAO,GAAG;;;aAGrB,QAAQ,GAAG,GAAG,QAAQ,GAAG;;;;;AAMtC,MAAM,kBAAkB,OAAO,MAAM;;;;;;;;;AAUrC,MAAa,aAAa,EACxB,UACA,GAAG,WAC4D;AAC/D,QAAO,oBAAC,iBAAD;EAAiB,GAAI;EAAO;EAA2B,CAAA;;AAGhE,MAAa,UAAU,OAAO,MAAM;;aAEvB,QAAQ,GAAG"}

package/dist/{text-B21s9mRZ.d.mts → text-BaQdW8qa.d.mts}

@@ -11,4 +11,4 @@ type ParagraphSize = 'lg' | 'md' | 'sm' | 'xs';
 declare const paragraphMixins: Record<ParagraphMixinSize, FlattenInterpolation<ThemeProps<DefaultTheme>>>;
 //#endregion
 export { displayMixins as a, paragraphMixins as c, ParagraphSize as i, HeadingSize as n, fontFamilyMixin as o, ParagraphMixinSize as r, headingMixins as s, DisplaySize as t };
-//# sourceMappingURL=text-B21s9mRZ.d.mts.map
+//# sourceMappingURL=text-BaQdW8qa.d.mts.map

package/dist/{theme-BzBpJXhO.d.mts → theme-D9Y6NOzb.d.mts}

@@ -151,4 +151,4 @@ declare const darkTheme: PersonaTheme;
 declare const marketingFontTheme: PersonaTheme;
 //#endregion
 export { darkTheme as a, Variant as i, PersonaTheme as n, defaultTheme as o, TextColors as r, marketingFontTheme as s, BackgroundColors as t };
-//# sourceMappingURL=theme-BzBpJXhO.d.mts.map
+//# sourceMappingURL=theme-D9Y6NOzb.d.mts.map

package/dist/theme.d.mts

@@ -1,2 +1,2 @@
-import { a as darkTheme, i as Variant, n as PersonaTheme, o as defaultTheme, r as TextColors, s as marketingFontTheme, t as BackgroundColors } from "./theme-BzBpJXhO.mjs";
+import { a as darkTheme, i as Variant, n as PersonaTheme, o as defaultTheme, r as TextColors, s as marketingFontTheme, t as BackgroundColors } from "./theme-D9Y6NOzb.mjs";
 export { BackgroundColors, PersonaTheme, TextColors, Variant, darkTheme, defaultTheme as default, marketingFontTheme };

package/dist/{types-CCvc590y.d.cts → types-BKEwt0uq.d.mts}

@@ -1,4 +1,4 @@
-import { a as FilterField, c as FilterOperator, u as FilterRuleValue } from "./types-B_HHNlia.cjs";
+import { a as FilterField, c as FilterOperator, u as FilterRuleValue } from "./types-mb3woqzE.mjs";
 import { ReactElement } from "react";
 
 //#region components/DataTable/TableControls/FiltersV2/value-controls/types.d.ts
@@ -42,4 +42,4 @@ interface ValueControlProps {
 }
 //#endregion
 export { ValueControlProps as t };
-//# sourceMappingURL=types-CCvc590y.d.cts.map
+//# sourceMappingURL=types-BKEwt0uq.d.mts.map

package/dist/{types-DEh_pXgS.d.mts → types-CjHuZoVJ.d.mts}

@@ -22,4 +22,4 @@ interface BaseActiveFilter<TFilter extends BaseFilterConfig = BaseFilterConfig>
 }
 //#endregion
 export { BaseActiveFilter as n, BaseFilterConfig as r, AttributeColumn as t };
-//# sourceMappingURL=types-DEh_pXgS.d.mts.map
+//# sourceMappingURL=types-CjHuZoVJ.d.mts.map

package/dist/{types-CkiXVJeR.d.cts → types-DVsBRqjZ.d.mts}

@@ -7,4 +7,4 @@ interface PaginationParams {
 }
 //#endregion
 export { PaginationParams as t };
-//# sourceMappingURL=types-CkiXVJeR.d.cts.map
+//# sourceMappingURL=types-DVsBRqjZ.d.mts.map

package/dist/{types-B_HHNlia.d.cts → types-mb3woqzE.d.mts}

@@ -3,14 +3,13 @@
  * Filter UI v2 — client-side state shape.
  *
  * Conceptual predicate (what the user sees in the bar):
- *   AND_perField(...topLevelRules) AND OR(...compound.groups)
+ *   AND(...topLevelRules) AND OR(...compound.groups)
  * where each `AndGroup` inside `compound.groups` is itself AND'd internally.
  *
- * - Simple pills compose into `topLevelRules`. Pills on DIFFERENT fields
- *   are AND'd together; multiple pills on the SAME field are OR'd
- *   together. AND'ing two equality predicates on a single field would
- *   always return zero rows, so multi-pill-per-field naturally means
- *   "is any of these values".
+ * - Simple pills compose into `topLevelRules` and every one of them
+ *   narrows the result set, on the same field as much as across fields.
+ *   OR lives inside a single pill's multi-select value ("is any of these
+ *   values") or in the Rules pill.
  * - The Rules pill owns `compound.groups` (OR-of-AND / DNF).
  */
 /** All available field types we render type-aware controls + operators for. */
@@ -155,4 +154,4 @@ type FilterSize = 'sm' | 'md';
 declare const EMPTY_FILTER_STATE: FilterStateV2;
 //#endregion
 export { FilterField as a, FilterOperator as c, FilterSize as d, FilterStateV2 as f, EMPTY_FILTER_STATE as i, FilterRule as l, CompoundExpression as n, FilterFieldSource as o, TopLevelFilterRule as p, DateRangeFilterValue as r, FilterFieldType as s, AndGroup as t, FilterRuleValue as u };
-//# sourceMappingURL=types-B_HHNlia.d.cts.map
+//# sourceMappingURL=types-mb3woqzE.d.mts.map

package/dist/types.d.mts

@@ -1,2 +1,2 @@
-import { n as BaseActiveFilter, r as BaseFilterConfig, t as AttributeColumn } from "./types-DEh_pXgS.mjs";
+import { n as BaseActiveFilter, r as BaseFilterConfig, t as AttributeColumn } from "./types-CjHuZoVJ.mjs";
 export { AttributeColumn, BaseActiveFilter, BaseFilterConfig };

package/dist/types2.d.mts

@@ -1,2 +1,2 @@
-import { a as FilterField, c as FilterOperator, d as FilterSize, f as FilterStateV2, i as EMPTY_FILTER_STATE, l as FilterRule, n as CompoundExpression, o as FilterFieldSource, p as TopLevelFilterRule, r as DateRangeFilterValue, s as FilterFieldType, t as AndGroup, u as FilterRuleValue } from "./types-D58IoRx6.mjs";
+import { a as FilterField, c as FilterOperator, d as FilterSize, f as FilterStateV2, i as EMPTY_FILTER_STATE, l as FilterRule, n as CompoundExpression, o as FilterFieldSource, p as TopLevelFilterRule, r as DateRangeFilterValue, s as FilterFieldType, t as AndGroup, u as FilterRuleValue } from "./types-mb3woqzE.mjs";
 export { AndGroup, CompoundExpression, DateRangeFilterValue, EMPTY_FILTER_STATE, FilterField, FilterFieldSource, FilterFieldType, FilterOperator, FilterRule, FilterRuleValue, FilterSize, FilterStateV2, TopLevelFilterRule };

package/dist/types3.d.mts

@@ -1,2 +1,2 @@
-import { t as ValueControlProps } from "./types-D7ppqnNj.mjs";
+import { t as ValueControlProps } from "./types-BKEwt0uq.mjs";
 export { ValueControlProps };

package/dist/types4.d.mts

@@ -1,2 +1,2 @@
-import { t as PaginationParams } from "./types-TV9nVfSe.mjs";
+import { t as PaginationParams } from "./types-DVsBRqjZ.mjs";
 export { PaginationParams };

package/dist/useComboboxFooterAction.d.mts

@@ -1,4 +1,4 @@
-import { p as FooterAction } from "./ComboboxBase-BsY7CYoB.mjs";
+import { p as FooterAction } from "./ComboboxBase-B8evOZpf.mjs";
 import { KeyboardEvent } from "react";
 
 //#region components/Combobox/useComboboxFooterAction.d.ts

package/dist/{useFilterStateV2-DCQghouq.d.mts → useFilterStateV2-CGzRyv0i.d.mts}

@@ -1,5 +1,5 @@
-import { f as FilterStateV2, l as FilterRule, n as CompoundExpression } from "./types-D58IoRx6.mjs";
-import { t as FieldRegistry } from "./FieldRegistry-rqSkjchY.mjs";
+import { f as FilterStateV2, l as FilterRule, n as CompoundExpression } from "./types-mb3woqzE.mjs";
+import { t as FieldRegistry } from "./FieldRegistry-COyIA4VU.mjs";
 
 //#region components/DataTable/TableControls/FiltersV2/useFilterStateV2.d.ts
 interface UseFilterStateV2Options {
@@ -90,4 +90,4 @@ interface UseFilterStateV2Result {
 declare function useFilterStateV2(options: UseFilterStateV2Options): UseFilterStateV2Result;
 //#endregion
 export { UseFilterStateV2Result as n, useFilterStateV2 as r, UseFilterStateV2Options as t };
-//# sourceMappingURL=useFilterStateV2-DCQghouq.d.mts.map
+//# sourceMappingURL=useFilterStateV2-CGzRyv0i.d.mts.map

package/dist/useFilterStateV2.d.mts

@@ -1,2 +1,2 @@
-import { n as UseFilterStateV2Result, r as useFilterStateV2, t as UseFilterStateV2Options } from "./useFilterStateV2-DCQghouq.mjs";
+import { n as UseFilterStateV2Result, r as useFilterStateV2, t as UseFilterStateV2Options } from "./useFilterStateV2-CGzRyv0i.mjs";
 export { UseFilterStateV2Options, UseFilterStateV2Result, useFilterStateV2 };

package/dist/{useFormField-D8mLsiQc.d.mts → useFormField-DhwEi45-.d.mts}

@@ -1,4 +1,4 @@
-import { t as ErrorProps } from "./ErrorProps-CN2XjaOX.mjs";
+import { t as ErrorProps } from "./ErrorProps-DX50vo-U.mjs";
 import * as _$react from "react";
 
 //#region components/FormControl/useFormField.d.ts
@@ -27,4 +27,4 @@ declare const useFormField: (props: Partial<FormControlContextProps>) => {
 };
 //#endregion
 export { FormControlContextProps as n, useFormField as r, FormControlContext as t };
-//# sourceMappingURL=useFormField-D8mLsiQc.d.mts.map
+//# sourceMappingURL=useFormField-DhwEi45-.d.mts.map

package/dist/useFormField.d.mts

@@ -1,2 +1,2 @@
-import { n as FormControlContextProps, r as useFormField, t as FormControlContext } from "./useFormField-D8mLsiQc.mjs";
+import { n as FormControlContextProps, r as useFormField, t as FormControlContext } from "./useFormField-DhwEi45-.mjs";
 export { FormControlContext, FormControlContextProps, useFormField as default };

package/dist/{useTableBoxDragAndDrop-DnbUToce.d.cts → useTableBoxDragAndDrop-CsnN52lx.d.mts}

@@ -66,4 +66,4 @@ declare const useTableBoxDragAndDrop: <T extends object>({
 }: UseTableBoxDragAndDropArgs<T>) => UseTableBoxDragAndDropResult;
 //#endregion
 export { ReorderConfig as n, useTableBoxDragAndDrop as r, DragDirection as t };
-//# sourceMappingURL=useTableBoxDragAndDrop-DnbUToce.d.cts.map
+//# sourceMappingURL=useTableBoxDragAndDrop-CsnN52lx.d.mts.map

package/dist/useTableBoxDragAndDrop.d.mts

@@ -1,2 +1,2 @@
-import { n as ReorderConfig, r as useTableBoxDragAndDrop, t as DragDirection } from "./useTableBoxDragAndDrop-BMo-iaUF.mjs";
+import { n as ReorderConfig, r as useTableBoxDragAndDrop, t as DragDirection } from "./useTableBoxDragAndDrop-CsnN52lx.mjs";
 export { DragDirection, ReorderConfig, useTableBoxDragAndDrop };

package/dist/{useToggle-Bo3yd14Y.mjs → useToggle-3k3EkV8V.mjs}

@@ -18,4 +18,4 @@ function useToggle(initialValue = false) {
 //#endregion
 export { useToggle as t };
 
-//# sourceMappingURL=useToggle-Bo3yd14Y.mjs.map
+//# sourceMappingURL=useToggle-3k3EkV8V.mjs.map

package/dist/{useToggle-Bo3yd14Y.mjs.map → useToggle-3k3EkV8V.mjs.map}

@@ -1 +1 @@
-{"version":3,"file":"useToggle-Bo3yd14Y.mjs","names":[],"sources":["../lib/useToggle.ts"],"sourcesContent":["import { useCallback, useState } from 'react';\n\ninterface UseToggleCallbacks {\n  set: (value: boolean) => void;\n  toggle: () => void;\n  enable: () => void;\n  disable: () => void;\n}\n\n/**\n * useToggle\n *\n * Boolean state hook that provides callbacks for enabling, disabling, flipping\n * and setting state.\n */\nexport default function useToggle(initialValue = false): [boolean, UseToggleCallbacks] {\n  const [value, setValue] = useState<boolean>(!!initialValue);\n  const set = useCallback((newValue: boolean) => setValue(newValue), []);\n  const toggle = useCallback(() => setValue(!value), [value]);\n  const enable = useCallback(() => setValue(true), []);\n  const disable = useCallback(() => setValue(false), []);\n  return [value, { set, toggle, enable, disable }];\n}\n"],"mappings":";;;;;;;;AAeA,SAAwB,UAAU,eAAe,OAAsC;CACrF,MAAM,CAAC,OAAO,YAAY,SAAkB,CAAC,CAAC,aAAa;AAK3D,QAAO,CAAC,OAAO;EAAE,KAJL,aAAa,aAAsB,SAAS,SAAS,EAAE,EAAE,CAIjD;EAAE,QAHP,kBAAkB,SAAS,CAAC,MAAM,EAAE,CAAC,MAAM,CAG9B;EAAE,QAFf,kBAAkB,SAAS,KAAK,EAAE,EAAE,CAEf;EAAE,SADtB,kBAAkB,SAAS,MAAM,EAAE,EAAE,CACR;EAAE,CAAC"}
+{"version":3,"file":"useToggle-3k3EkV8V.mjs","names":[],"sources":["../lib/useToggle.ts"],"sourcesContent":["import { useCallback, useState } from 'react';\n\ninterface UseToggleCallbacks {\n  set: (value: boolean) => void;\n  toggle: () => void;\n  enable: () => void;\n  disable: () => void;\n}\n\n/**\n * useToggle\n *\n * Boolean state hook that provides callbacks for enabling, disabling, flipping\n * and setting state.\n */\nexport default function useToggle(initialValue = false): [boolean, UseToggleCallbacks] {\n  const [value, setValue] = useState<boolean>(!!initialValue);\n  const set = useCallback((newValue: boolean) => setValue(newValue), []);\n  const toggle = useCallback(() => setValue(!value), [value]);\n  const enable = useCallback(() => setValue(true), []);\n  const disable = useCallback(() => setValue(false), []);\n  return [value, { set, toggle, enable, disable }];\n}\n"],"mappings":";;;;;;;;AAeA,SAAwB,UAAU,eAAe,OAAsC;CACrF,MAAM,CAAC,OAAO,YAAY,SAAkB,CAAC,CAAC,aAAa;AAK3D,QAAO,CAAC,OAAO;EAAE,KAJL,aAAa,aAAsB,SAAS,SAAS,EAAE,EAAE,CAIjD;EAAE,QAHP,kBAAkB,SAAS,CAAC,MAAM,EAAE,CAAC,MAAM,CAG9B;EAAE,QAFf,kBAAkB,SAAS,KAAK,EAAE,EAAE,CAEf;EAAE,SADtB,kBAAkB,SAAS,MAAM,EAAE,EAAE,CACR;EAAE,CAAC"}

package/dist/useTruncation.d.mts

@@ -1,4 +1,4 @@
-import { i as ComboboxOption } from "./ComboboxBase-BsY7CYoB.mjs";
+import { i as ComboboxOption } from "./ComboboxBase-B8evOZpf.mjs";
 import { MutableRefObject, RefObject } from "react";
 
 //#region components/Combobox/useTruncation.d.ts

package/dist/{utilities-mSlaTrjB.d.cts → utilities-DnSIlR1i.d.mts}

@@ -6,4 +6,4 @@
 type RequireOneOf<T, Keys extends keyof T = keyof T> = Pick<T, Exclude<keyof T, Keys>> & { [K in Keys]-?: Required<Pick<T, K>> & Partial<Pick<T, Exclude<Keys, K>>> }[Keys];
 //#endregion
 export { RequireOneOf as t };
-//# sourceMappingURL=utilities-mSlaTrjB.d.cts.map
+//# sourceMappingURL=utilities-DnSIlR1i.d.mts.map

package/dist/utilities.d.mts

@@ -1,2 +1,2 @@
-import { t as RequireOneOf } from "./utilities-BO_95qFA.mjs";
+import { t as RequireOneOf } from "./utilities-DnSIlR1i.mjs";
 export { RequireOneOf };

package/dist/utils/storybook.mjs

@@ -1,4 +1,4 @@
-import { n as Stack } from "../Stack-Bl54WmhY.mjs";
+import { n as Stack } from "../Stack-ckRN7LrP.mjs";
 import { jsx } from "react/jsx-runtime";
 //#region utils/storybook.tsx
 const withStack = (Story) => {

package/dist/utils/testing.d.mts

@@ -1,6 +1,6 @@
+import { ReactElement } from "react";
 import * as _$_testing_library_react0 from "@testing-library/react";
 import { RenderOptions, screen } from "@testing-library/react";
-import { ReactElement } from "react";
 import * as _$_testing_library_dom_types_queries0 from "@testing-library/dom/types/queries";
 
 //#region utils/testing.d.ts

package/dist/utils/testing.mjs

@@ -1,7 +1,7 @@
 import PDSProvider from "../lib/PDSProvider.mjs";
+import { RouterProvider } from "react-aria-components";
 import { Fragment, jsx } from "react/jsx-runtime";
 import { render, screen } from "@testing-library/react";
-import { RouterProvider } from "react-aria-components";
 import { RouterProvider as RouterProvider$1, createMemoryRouter } from "react-router-dom";
 //#region utils/testing.tsx
 const AllTheProviders = ({ children, includeRouter = false }) => {

package/dist/utils.d.mts

@@ -1,4 +1,4 @@
-import { u as FilterRuleValue } from "./types-D58IoRx6.mjs";
+import { u as FilterRuleValue } from "./types-mb3woqzE.mjs";
 
 //#region components/DataTable/TableControls/FiltersV2/value-controls/utils.d.ts
 /**

package/dist/{validation-CJymv6JE.d.cts → validation-BdP2vajF.d.mts}

@@ -1,5 +1,5 @@
-import { f as FilterStateV2, l as FilterRule } from "./types-B_HHNlia.cjs";
-import { t as FieldRegistry } from "./FieldRegistry-OX60T3hr.cjs";
+import { f as FilterStateV2, l as FilterRule } from "./types-mb3woqzE.mjs";
+import { t as FieldRegistry } from "./FieldRegistry-COyIA4VU.mjs";
 
 //#region components/DataTable/TableControls/FiltersV2/validation.d.ts
 /**
@@ -48,4 +48,4 @@ declare function pruneToRegistry(state: FilterStateV2, registry: FieldRegistry |
 declare function hasCompleteValue(rule: FilterRule, registry: FieldRegistry): boolean;
 //#endregion
 export { isFilterStateV2 as n, pruneToRegistry as r, hasCompleteValue as t };
-//# sourceMappingURL=validation-CJymv6JE.d.cts.map
+//# sourceMappingURL=validation-BdP2vajF.d.mts.map

package/dist/validation.d.mts

@@ -1,2 +1,2 @@
-import { n as isFilterStateV2, r as pruneToRegistry, t as hasCompleteValue } from "./validation-vLh3t2dk.mjs";
+import { n as isFilterStateV2, r as pruneToRegistry, t as hasCompleteValue } from "./validation-BdP2vajF.mjs";
 export { hasCompleteValue, isFilterStateV2, pruneToRegistry };

package/dist/{value-control-resolver-CE-bqdAl.d.mts → value-control-resolver-CiGEHQAc.d.mts}

@@ -1,4 +1,4 @@
-import { a as FilterField, c as FilterOperator, u as FilterRuleValue } from "./types-D58IoRx6.mjs";
+import { a as FilterField, c as FilterOperator, u as FilterRuleValue } from "./types-mb3woqzE.mjs";
 import { ReactNode } from "react";
 
 //#region components/DataTable/TableControls/FiltersV2/FilterBar/value-control-resolver.d.ts
@@ -43,4 +43,4 @@ type ValueControlResolver = (opts: ResolveValueControlOptions) => ReactNode | un
 declare function resolveValueControl(opts: ResolveValueControlOptions, hostResolver?: ValueControlResolver): ReactNode;
 //#endregion
 export { ValueControlResolver as n, resolveValueControl as r, ResolveValueControlOptions as t };
-//# sourceMappingURL=value-control-resolver-CE-bqdAl.d.mts.map
+//# sourceMappingURL=value-control-resolver-CiGEHQAc.d.mts.map

package/dist/value-control-resolver.d.mts

@@ -1,2 +1,2 @@
-import { n as ValueControlResolver, r as resolveValueControl, t as ResolveValueControlOptions } from "./value-control-resolver-CE-bqdAl.mjs";
+import { n as ValueControlResolver, r as resolveValueControl, t as ResolveValueControlOptions } from "./value-control-resolver-CiGEHQAc.mjs";
 export { ResolveValueControlOptions, ValueControlResolver, resolveValueControl };

package/llms.txt

@@ -0,0 +1,43 @@
+# @persona/design-system
+
+> React components and layouts for Persona UI. Design tokens (`Color`, `Spacing`, `Typography`) come from the companion package `@persona/design-tokens`.
+
+Agent guidance ships inside this package. Before reading `dist/` bundles or reverse-engineering
+component APIs, read the skills below — they cover component selection, props, and common
+pitfalls. In a repo with TanStack Intent, run `yarn intent list` / `yarn intent load
+@persona/design-system#ui-authoring`. Without Intent, read the same files directly from
+`node_modules/@persona/design-system/skills/`.
+
+For exact prop types, prefer the published type declarations (`dist/**/*.d.mts`, e.g.
+`dist/components/Table/index.d.mts`) over the minified `*.mjs` bundles.
+
+## Skills
+
+- [ui-authoring](skills/ui-authoring/SKILL.md): component-first table (which component for which need), design tokens, table guidelines (DataTable vs TableBox vs TableLayout), loading/empty states, forms, testing, Storybook, charts
+- [Components reference](skills/ui-authoring/COMPONENTS.md): props + patterns for ConfigFormGroup, ListBox, TableBox, Card, Modal, form state hook
+- [Examples](skills/ui-authoring/EXAMPLES.md): copy-paste patterns (Buttons, Forms, Modals, DataTable, TabBar, Tooltip, Spinner, Banner, Sticker, Stack, Text)
+- [Token reference](skills/ui-authoring/REFERENCE.md): full Color / Spacing / Typography catalog
+
+## Imports
+
+Import from subpaths, not the package root — e.g.
+`import { Button } from '@persona/design-system/components/Button'`.
+The full export map is in `package.json#exports`; components live under
+`./components/<Name>`, patterns under `./patterns/<Name>`, mixins/variables/utils under
+their own subpaths.
+
+## Common components
+
+- Layout: `Stack` / `HStack` (components/Stack), `Spacer`
+- Text: `Heading`, `Paragraph`, `Label` (components/Text)
+- Tables: `DataTable` (data views w/ pagination + sorting), `TableBox` (editable form tables), `TableLayout` + `Table`/`TableRow`/`TableCell`/`TableHeaderCell` primitives (components/Table) — `TableLayout` has built-in `isLoading`/`isEmpty`/`nullState`/`showHeader` handling
+- Page chrome: `PageHeader` (title or breadcrumbs variant), `Breadcrumbs`, `TabBar`
+- Feedback: `Spinner`, `Banner`, `Toast`, `LoadingShimmer`, `ProgressBar`
+- Overlays: `Modal`, `Popover`, `Tooltip` / `TextUnderlineTooltip`, `DropdownMenu`
+- Forms: `ConfigFormGroup`, `FormField` (`TextField`, `TextAreaField`, `TableBoxField`), `Input`, `TextArea`, `Select`, `Combobox`, `Checkbox`, `Radio`, `Toggle`, `DatePicker`
+- Status: `Sticker` (status badges), `Badge` (counts), `StatusIndicator`
+
+## Testing
+
+Use `dsRender` from `@persona/design-system/utils/testing` (wraps ThemeProvider); prefer
+role/label/text queries over test IDs.