@beehexa/design-rules 0.0.0-stage → 2611.3.3

package/README.md

@@ -1,3 +1,57 @@
-# Temporary Holding Version
+# @beehexa/design-rules
 
-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.
+Complete source-content rules for installed tools and coding agents, not a short curated summary or a list of website links. Unreleased local-development package (`0.0.0`, `private: true`); no release or publication is authorized by its presence.
+
+## Discover, list, read and search
+
+```js
+import { catalog, listRules, readRule, searchRules } from '@beehexa/design-rules';
+
+const usage = readRule('en/foundations/styles/color/usage');
+console.log(usage?.title, usage?.status, usage?.body);
+const matches = searchRules('focus');
+const planned = listRules().filter((rule) => rule.status === 'planned');
+```
+
+`catalog` and `listRules()` expose the complete document array. `readRule(id)` returns the document or `undefined` for an unknown ID. `searchRules(query)` performs a case-insensitive substring search over the full ID, title and MDX body; an empty query returns all documents. APIs are local and synchronous, with no network or website/checkout dependency once built and installed. Treat returned data as read-only.
+
+Every catalog entry has:
+
+| Field | Meaning |
+| --- | --- |
+| `id` | Stable locale-prefixed source path without extension, such as `en/foundations/styles/color/index`. Overview IDs retain `index`; Vietnamese IDs begin `vi/`. |
+| `path` | Original source file path, including `.md`/`.mdx`. |
+| `documentPath` | `docs/` plus `path`, relative to installed `dist/`. |
+| `locale` | `en` or `vi`. No synthetic translations are generated. |
+| `kind` | `guidance`, historical `news`, or source proposal `reference`. News/reference are not silently promoted into normative usage requirements. |
+| `title` | Source title; component tabs use the component metadata title plus tab name. |
+| `status` | `active` for authored content; `planned` for a source planned list or empty body. **Active does not mean final, approved or GA.** |
+| `releasePhase` | Original source release phase, including component metadata when present; `null` when unspecified. This is distinct from active/planned. |
+| `planned` | Exact source list of unfinished topics, retained even when a page has some body content. |
+| `body` | Full MDX/Markdown after frontmatter, retaining examples, imports and component calls. |
+| `raw` | Complete original document, including frontmatter, byte-for-byte UTF-8 text. |
+| `frontmatter` | Parsed original frontmatter for consumers needing additional metadata. |
+
+`@beehexa/design-rules/catalog.json` is the same complete payload for non-JavaScript tools. Resolve `@beehexa/design-rules/agent` for installed agent instructions. Resolve `@beehexa/design-rules/docs/` + a rule's `path` for its raw document, or read `dist/docs/<original path>` next to the installed catalog. `@beehexa/design-rules/package.json` exposes installed origin/version metadata.
+
+## Complete local source, not rendered HTML
+
+The build traverses **all** `src/content/` and `src/content-vi/` documents, including every usage, accessibility, code and examples page, token/style/layout/locale guideline, planned stub, component tab, and historical news entry. Component `meta.json` files remain in the raw payload. The source structure proposal is separately cataloged as `en/reference/structure-proposal`.
+
+Supporting raw sources are included at their original paths below `dist/docs/`: the complete `src/components`, `src/lib`, `src/styles`, `src/brand`, `public` and `tokens` trees, `src/content.config.ts`, and shared token-utils implementation/declarations. This preserves instructions represented by MDX component examples/tables as well as written prose, brand references, images, downloads and font files. The payload is source for reading; it is not pre-rendered HTML, a compiled component library, or a vendored copy of external framework/icon npm dependencies. Existing asset licenses still apply.
+
+Install a local reference to `packages/design-rules` until managers explicitly approve release (for example Yarn `portal:../beehexa.design/packages/design-rules` after the producer build). Do not scrape the site, maintain dashboard-owned copies, or link consumers to a checkout instead of installing content.
+
+Local references are **local-development only**. Consumer CI requires actual released npm versions and must never check out sibling repositories or build from sibling paths. Producer CI stays single-repository. Release, deployment and CI execution are not local-work prerequisites; until a real authorized release exists, do not invent a cross-repository consumer CI fallback.
+
+## Applying the rules and unresolved source gaps
+
+Read related usage, code, accessibility, responsive, theme and locale documents before implementing. `@beehexa/design-tokens` supplies actual reusable values; `tokenInfo` supplies descriptions and raw/resolved mode metadata. Neither token availability nor a description is the complete rulebook. This package supplies that source rulebook without changing its authority.
+
+There are **no product/dashboard exemptions**. Missing guidance is an upstream source gap, not permission to invent a downstream standard. Pages marked planned remain explicitly planned. The source currently has unfinished areas such as data visualization; the generated agent entrypoint lists every actual planned document and its planned topics from the source. The component catalog and release phases remain incomplete, and not every English page has a Vietnamese translation. A missing release phase is not GA. The website and its structure proposal describe a working design-system proposal, not a declaration that all standards are finalized. External framework/icon APIs remain external dependencies.
+
+The dashboard's 14px root uses the token package's rem*16 pixel CSS only as compatibility debt; it receives no alternate design scale or rule exemption. Improvements or clarifications belong in the beehexa.design source, followed by package generation—not a consumer patch/copy.
+
+## Producer commands
+
+From the source root: `npm ci`, `npm run build:packages`, `npm run check:packages`, `npm run pack:packages`. `npm run build -w @beehexa/design-rules` and its `prepack` generate the package directly from this repository. Checks compare every emitted artifact with current source inputs and reject stale/missing/extra outputs; no dashboard checkout is involved. The package contains ESM, declarations, full JSON catalog, agent instructions, all raw source/support documents and this README. Building/packing locally does not authorize publishing.

package/dist/AGENTS.md

@@ -0,0 +1,24 @@
+# Beehexa design usage: installed source authority
+
+Use this installed package, not scraped HTML, a dashboard-owned snapshot, or a website URL as a substitute for content.
+
+1. Import { catalog, listRules, readRule, searchRules } from '@beehexa/design-rules'.
+2. Discover by stable locale-prefixed ID; search title, ID and full body (case insensitive), then read complete documents. IDs retain /index for overview pages.
+3. Read each result's status, planned list and releasePhase before applying it. active means authored content, NOT final/GA. planned is an unfinished source area, NOT permission to invent a standard. null releasePhase means the source did not specify one.
+4. Read related usage, code, accessibility, responsive, theme and locale pages, not just the first token match. English is the baseline; translations exist only where supplied. No synthetic translations or missing-page placeholders are generated.
+5. All raw files are installed below this directory's docs/ with original source paths. Resolve '@beehexa/design-rules/docs/' + rule.path with your package resolver. body retains MDX examples and imports; raw includes exact frontmatter. Supporting Astro/TypeScript, brand reference files, public assets and tokens are also included there. This is source for reading, not a pre-rendered website or component runtime.
+6. Token values come from @beehexa/design-tokens; tokenInfo provides per-token descriptions, aliases and mode metadata. Metadata is NOT the complete usage rulebook. Read this catalog for allowed roles, combinations, interaction, layout and accessibility semantics.
+7. There are NO product/dashboard exemptions. Missing source guidance is a gap to report to the source owners, not an exemption. Do not create a downstream token or rule copy. Local unreleased package references are for LOCAL DEVELOPMENT ONLY until managers explicitly authorize release. Consumer CI must use actual released npm versions; it must never check out sibling repositories, build from sibling checkouts or require release/deployment/CI execution for local work. Producer CI is single-repository.
+8. The pixel CSS entrypoint is rem*16 compatibility for the dashboard's current 14px root; this is migration debt, not an alternate design scale or a root-font exemption. Native rem is the source convention. Token names and TypeScript key typing remain shared.
+
+Source gaps retained verbatim (8 planned documents):
+- en/foundations/styles/data-visualization: A chart palette for series, with contrast in light and dark; Status colours in charts; Chart types and when to use each; Axis, legend, tooltip and number formats; Accessible charts: not by colour alone, text alternatives
+- en/foundations/styles/illustration: When to use a diagram, an illustration or a screenshot; The diagram style from the brand guide: structured, built on the hexagon grid; Empty states and onboarding images
+- en/foundations/styles/opacity: Where transparency is allowed: the scrim behind dialogs, image overlays; Why hover, pressed and disabled use colour steps, not opacity; Opacity tokens, if any are needed
+- en/foundations/styles/z-index: Layer names and their order; Which layer each overlay uses: dropdown, popover, tooltip, dialog, drawer, toast; How layering pairs with elevation
+- vi/foundations/styles/data-visualization: Bảng màu cho các chuỗi dữ liệu, đủ tương phản ở light và dark; Màu trạng thái trong biểu đồ; Các loại biểu đồ và khi nào dùng; Trục, chú giải, tooltip và định dạng số; Biểu đồ dễ tiếp cận: không chỉ dựa vào màu, có phần mô tả bằng chữ
+- vi/foundations/styles/illustration: Khi nào dùng sơ đồ, hình minh hoạ hay ảnh chụp màn hình; Phong cách sơ đồ theo brand guide: có cấu trúc, dựng trên lưới lục giác; Hình cho trạng thái trống và onboarding
+- vi/foundations/styles/opacity: Chỗ được dùng độ trong suốt: lớp phủ sau dialog, lớp phủ trên ảnh; Vì sao hover, pressed và disabled dùng bậc màu, không dùng độ mờ; Token độ mờ, nếu cần
+- vi/foundations/styles/z-index: Tên các lớp và thứ tự; Mỗi lớp phủ dùng lớp nào: dropdown, popover, tooltip, dialog, drawer, toast; Lớp và đổ bóng đi cùng nhau thế nào
+
+The source website is a working proposal. Component coverage and release phases are incomplete; some docs remain planned. Historical news and the structure proposal are labeled kind=news/reference, not silently promoted into normative usage rules. Referenced external framework/icon APIs and fonts retain their upstream licenses; this package does not vendor npm dependencies or execute MDX.