@akanjs/cli 2.3.13 → 2.4.0-rc.1

package/guidelines/componentRule/componentRule.instruction.md

@@ -15,6 +15,14 @@ Use this for shared UI rules across module, scalar, app UI, and docs components.
 - Client components can use store hooks and event handlers where interaction is required.
 - Use generated model types from app client or module constants; do not invent duplicate UI-only model shapes.
 
+## Customizing Framework Components (Slot Overrides)
+- When a default `akanjs/ui` component (Button, Select, Modal, Table, Input, Radio, DatePicker, Loading, …) is too restrictive for the design, re-skin it per route with a slot override instead of forking, wrapping every call site, or fighting it with `!important`.
+- Write the drop-in replacement in `apps/<app>/ui/`, typed against the slot contract — `AkanModalComponent`, or `AkanUiOverrides["<Slot>"]` for any other slot — so it is compile-checked as a real substitute. Compose the framework's headless parts (e.g. `Dialog`) rather than re-implementing focus trapping, portals, or scroll-lock.
+- Bind it in a logic-free `page/**/_overrides.tsx` manifest: imports plus a single `export default override({ Slot: BrandComponent })` (from `akanjs/ui`), no `"use client"`.
+- Place the manifest at `page/` for an app-wide skin, or inside a route group/segment to scope it; nested manifests merge over ancestors slot-by-slot (closest ancestor wins, unlisted slots keep inheriting).
+- Compound components expose one slot per leaf named `<Base><Sub>` (e.g. `InputPassword`, `RadioItem`, `LoadingSpin`); override only the leaves you need.
+- See the `references/ui/customize` docs page for the full slot list and examples.
+
 ## Codegen Rules
 - Do not put business workflow decisions in render code.
 - Do not use undocumented UI components or props.

package/guidelines/cssRule/cssRule.instruction.md

@@ -15,6 +15,24 @@ Use TailwindCSS and DaisyUI in a theme-safe, composable way for Akan UI and docs
 - Use consistent density and spacing within one component family.
 - Keep custom CSS files rare and scoped to cases utilities cannot express cleanly.
 
+## Theme Customization (`apps/<app>/page/styles.css`)
+- The app theme is defined in `apps/<app>/page/styles.css` with daisyUI v5 `@plugin "daisyui/theme"` blocks (typically `light` and a `default: true` `dark`).
+- Brand-level customization means tuning the whole theme block, not only the color tokens. A theme that only changes `--color-*` still looks like the default framework skin.
+- Color tokens: `--color-primary`, `--color-secondary`, `--color-accent`, `--color-neutral`, `--color-info`, `--color-success`, `--color-warning`, `--color-error`, `--color-base-100/200/300`, and their `*-content` pairs.
+- Shape and feel tokens (set these too):
+  - `--radius-selector` — rounding for checkbox, toggle, badge.
+  - `--radius-field` — rounding for button, input, select, tab.
+  - `--radius-box` — rounding for card, modal, alert.
+  - `--size-selector`, `--size-field` — base scale (density) of selector and field controls.
+  - `--border` — component border width (e.g. `1px`, `2px`).
+  - `--depth` — `0` flat, `1` adds a subtle 3D lift to components.
+  - `--noise` — `0` off, `1` adds a grain texture to surfaces.
+- Keep shape/feel tokens consistent across the light and dark theme blocks unless the design deliberately differs by mode.
+
+## When Utilities Are Not Enough
+- Prefer theme tokens and DaisyUI component classes over one-off utility stacks that re-implement a component's look.
+- When a framework `akanjs/ui` component is structurally too restrictive, re-skin it with a `page/**/_overrides.tsx` slot override (see the componentRule guideline), not with `!important` utilities or a fork.
+
 ## Codegen Rules
 - Do not hardcode hex colors or one-off brand colors unless the existing file already defines that design system.
 - Do not use important flags to fight component composition.

package/guidelines/framework/framework.instruction.md

@@ -22,6 +22,12 @@ Use this as the compact framework context for AI codegen. It should explain how
 - Keep business decisions in constant, document, or service; keep API exposure in signal; keep client coordination in store; keep rendering in UI files.
 - Use direct module imports where scanner rules expect them, and avoid inventing new top-level app folders.
 
+## Theming And UI Customization
+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 theme is one or more daisyUI v5 `@plugin "daisyui/theme"` blocks. Match the brand by tuning the whole block, not only the `--color-*` tokens: set corner rounding (`--radius-selector`, `--radius-field`, `--radius-box`), control density (`--size-selector`, `--size-field`), outline weight (`--border`), and surface treatment (`--depth`, `--noise`). New workspaces ship these knobs at neutral defaults so they are visible to tune. Fetch `get_guideline` with `cssRule` for the full variable reference before a deep theme pass.
+- **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
 - The instruction points to current docs pages, not removed docs routes.
 - Generated examples use current Akan builder APIs and scanner-friendly filenames.