@akanjs/cli 3.0.0-alpha.3 → 3.0.0-alpha.31

package/guidelines/cssRule/cssRule.instruction.md

@@ -55,6 +55,13 @@ Screen code is invariant — a plain `<Button variant="primary">` never changes.
 - Switching themes is toggling the `data-theme` attribute. Keep every token defined in both the dark and light blocks.
 - Radius uses `rounded-box` (cards/modals), `rounded-field` (buttons/inputs), `rounded-selector` (toggles/checkboxes).
 
+## Lib-Owned Tokens (`libs/<lib>/ui/tokens.css`)
+- A lib that needs colors of its own — vendor brand colors pinned by someone else's guide (Kakao `#fee500`, Naver `#1ec800`), fixed in-game surfaces — declares them **once** in `libs/<lib>/ui/tokens.css`. Never copy the block into each app's stylesheet.
+- The file is collected automatically: every app whose page graph reaches that lib compiles it, ordered **ahead of** the app's own stylesheets, so the app wins on any variable both declare. There is nothing to import and no sync step to remember; two libs both declaring one variable resolve in lib-name order, so do not rely on that.
+- Declare plain custom properties under `:root`, not a Tailwind `@theme` extension: the color vocabulary is closed per stylesheet, so `bg-kakao` would generate no CSS. Reference them as `bg-[var(--kakao)]` / `text-[var(--kakao-foreground)]`, which `no-arbitrary-color` allows by design (a `var()` reference is not an arbitrary color literal).
+- Theme-following colors still belong to the app: a lib token is for a color that must **not** change with `data-theme`.
+- An `@import` the CSS pipeline cannot resolve fails the build; it is never dropped. A stylesheet under `page/` that no route imports is compiled by nothing and warns at build time.
+
 ## Codegen Rules
 - Do not hardcode hex or raw-palette colors (`bg-red-500`, `#ff0000`); use semantic tokens.
 - Do not put inline color literals in `style={{ }}`; use token classes.

package/guidelines/framework/framework.instruction.md

@@ -26,6 +26,7 @@ Use this as the compact framework context for AI codegen. It should explain how
 When a request implies a distinct look and feel, do not stop at colors — customize both the theme and, when needed, the components.
 
 - **Theme (`apps/<app>/page/styles.css`).** The app imports Tailwind and `akanjs/ui/styles.css`, then overrides semantic token *values* per theme under `:root, [data-theme="dark"]` and `[data-theme="light"]` (`--background`, `--foreground`, `--primary`, `--muted`, `--border`, … each with a `-foreground` pair for text). The framework maps them to Tailwind color names, so `bg-primary` / `text-foreground` follow the `data-theme` attribute; corner rounding uses `--radius-box` / `--radius-field`. Fetch `get_guideline` with `cssRule` for the full token set before a deep theme pass.
+- **Lib tokens (`libs/<lib>/ui/tokens.css`).** Colors a lib's own components pin — a vendor brand color, a fixed surface — are declared once there as plain `:root` custom properties and compiled into every app that reaches the lib, ahead of the app's stylesheets. Reference them as `bg-[var(--kakao)]`; never copy the block into each app.
 - **Components (`page/**/_overrides.tsx`).** When a default `akanjs/ui` component (Button, Modal, Table, Input, Select, …) is too restrictive for the design, re-skin it per route instead of forking, wrapping, or fighting it with utility classes. Write a drop-in replacement in `apps/<app>/ui/` typed against the slot contract (`AkanModalComponent`, or `AkanUiOverrides["<Slot>"]`), composing the framework's headless parts, then bind it in a `page/**/_overrides.tsx` manifest with a single `export default override({ Slot: BrandComponent })`. Overrides cascade down the route tree like layouts (closest ancestor wins). Fetch `get_guideline` with `componentRule` and read the `references/ui/customize` docs page for the slot list and patterns.
 
 ## Review Checklist

package/guidelines/workspaceOnboarding/workspaceOnboarding.generate.json

@@ -0,0 +1,24 @@
+{
+  "title": "Workspace Onboarding",
+  "description": "Product-workspace orientation — layout, decision matrix, workflow recipes, and query gotchas",
+  "group": "core",
+  "codegenPriority": 2,
+  "deprecated": false,
+  "scans": [],
+  "update": {
+    "filePath": "./workspaceOnboarding.instruction.md",
+    "contents": [
+      "workspace layout and generated files",
+      "agent workflow and common commands",
+      "where-do-I-put-this decision matrix",
+      "workflow recipes",
+      "modeling and query gotchas"
+    ],
+    "rules": [
+      "Use current Akan APIs only",
+      "Write for someone building a product on Akan, not for someone changing Akan",
+      "Refer to the app as <%= appName %>; the renderer substitutes the workspace's first app",
+      "Do not repeat a rule that the conventions guideline already states"
+    ]
+  }
+}