pasika 0.1.4 → 0.1.6

package/docs/styling-guide/rules/theme-and-utility-definition-rule.md

@@ -1,129 +1,86 @@
 # Theme and Utility Definition Rule
 
-Tailwind theme namespaces generate broad utility APIs, while custom utilities expose one intentional treatment. This rule resets unused defaults and chooses the narrowest public API for every project-owned design value.
+This rule decides when styling stays with one component or becomes a shared utility, and how project values are exposed through Tailwind.
 
-- The project MUST reset Tailwind's default theme with `--*: initial` and explicitly define every theme value it uses.
-- A static design value intended to generate a Tailwind utility namespace MUST be defined through `@theme`.
-- A static theme value MUST be defined directly in plain `@theme` when it has no runtime variable indirection.
-- A theme value that references a CSS variable changed by a theme selector or custom variant MUST be mapped through `@theme inline`.
-- A property-specific value MUST remain a private CSS variable and be exposed through one named `@utility` rather than a broad theme namespace.
-- A repeated multi-property treatment MUST be defined through one named `@utility`.
-- Project-owned style declarations inside `@utility` and unavoidable global selectors MUST use `@apply`.
-- A custom utility MUST use Tailwind custom-property or arbitrary-property utility syntax through `@apply` when no named built-in utility represents the property value.
-- A custom utility that owns interaction behavior MUST keep its hover, active, focus, and disabled treatments in the same utility block.
-- Component markup MUST NOT contain literal arbitrary values in place of missing project tokens or utilities.
+- Styling used by only one component MUST stay in that component file as static Tailwind utility classes and MUST NOT be moved to the global stylesheet.
+- A style or group of styles that two or more components use together and should change together MUST become one named custom utility. The group MAY include utilities generated by theme variables, built-in utilities, other custom utilities, and interaction styles.
+- A value that needs at least two utility classes from the same [Tailwind theme-variable namespace](https://tailwindcss.com/docs/theme#theme-variable-namespaces) MUST use that namespace and have the same name in `:root`.
+- A CSS variable intended only for a background MUST be named `--<role>-canvas`, and one intended only for readable text MUST be named `--<role>-ink`. When a named custom utility exposes one of those values by itself, it MUST use `bg-<role>-canvas` or `text-<role>-ink`.
+- A repeated combination of canvas, ink, and related styles MUST become a `*-surface` custom Tailwind utility that owns the combination.
+- A custom utility MUST use `@apply` for every styling declaration added by the project. When no named built-in utility represents a property value, it MUST apply the Tailwind custom-property or arbitrary-property utility instead.
 
-## Incorrect — Default Theme Kept and Property-Specific Color Exposed Broadly
+## Incorrect — Property-Specific Color Exposed Broadly
 
 ```css
-@theme {
-  --color-header-ink: var(--header-ink);
+:root {
+  --color-header-ink: #111827;
+}
+
+@theme inline {
+  --color-header-ink: var(--color-header-ink);
 }
 ```
 
 ```tsx
 <h1 className="text-header-ink">Title</h1>
-<div className="bg-header-ink" />
 ```
 
-Why: the default theme remains active, and registering a text-only color in `--color-*` also creates unintended background, border, ring, and other color utilities.
+Why: registering a text-only color in `--color-*` also creates unintended background, border, ring, and other color utilities.
 
-## Correct — Custom Theme and Property-Specific Utility
+## Correct — Property-Specific Utility
 
 ```css
 :root {
   --header-ink: #111827;
 }
 
-@theme {
-  --*: initial;
-  --spacing: 0.25rem;
-  --font-body: Inter, sans-serif;
-}
-
-@utility text-header {
+@utility text-header-ink {
   @apply text-(--header-ink);
 }
 ```
 
 ```tsx
-<h1 className="text-header">Title</h1>
-```
-
-Why: only explicitly defined theme values remain available, while the private header color exposes exactly one text utility.
-
-## Incorrect — Runtime Theme Variable Mapped Without `inline`
-
-```css
-:root {
-  --primary: #7c3aed;
-}
-
-.dark {
-  --primary: #a78bfa;
-}
-
-@theme {
-  --color-primary: var(--primary);
-}
-```
-
-Why: the public token uses runtime variable indirection without the inline mapping intended for selector-driven theme values.
-
-## Correct — Runtime Theme Variable Mapped Inline
-
-```css
-:root {
-  --primary: #7c3aed;
-}
-
-.dark {
-  --primary: #a78bfa;
-}
+// SiteHeader.tsx
+<h1 className="text-header-ink">Title</h1>
 
-@theme inline {
-  --color-primary: var(--primary);
-}
+// PageHeader.tsx
+<h2 className="text-header-ink">Settings</h2>
 ```
 
-Why: generated color utilities reference the selector-driven runtime value directly.
+Why: both components use the same text-only color, so one named text utility owns it without creating background, border, or ring utilities.
 
-## Incorrect — Treatment Split Across Utilities and Raw Declarations
+## Incorrect — Property-Specific Colors Exposed Broadly
 
 ```css
-@utility surface-primary {
-  background-color: var(--primary-canvas);
-}
-
-@utility surface-primary-hover {
-  background-color: var(--primary-canvas-hover);
+@theme {
+  --color-primary-canvas: #d87943;
+  --color-primary-ink: #ffffff;
 }
 ```
 
 ```tsx
-<button className="surface-primary hover:surface-primary-hover">Save</button>
+<button className="bg-primary-canvas text-primary-ink">Save</button>
+<button className="bg-primary-canvas text-primary-ink">Continue</button>
 ```
 
-Why: the treatment is split across public utilities, its state is reconstructed in markup, and project-owned declarations bypass Tailwind composition.
+Why: property-specific colors are exposed as broad Tailwind colors, and the repeated combination has no named owner.
 
-## Correct — Complete Treatment Composed with `@apply`
+## Correct — Color Roles Expose Their Intended API
 
 ```css
-@utility surface-primary {
-  @apply rounded-md bg-(--primary-canvas) px-3 py-2 text-(--primary-ink);
-
-  &:hover {
-    @apply bg-(--primary-canvas-hover);
-  }
+:root {
+  --primary-canvas: #d87943;
+  --primary-ink: #ffffff;
+}
 
-  &:focus-visible {
-    @apply outline-2 outline-(--focus-ring);
-  }
+@utility primary-surface {
+  @apply bg-(--primary-canvas) text-(--primary-ink);
 }
 ```
 
 ```tsx
-<button className="surface-primary">Save</button>
+<button className="primary-surface">Save</button>
+<button className="primary-surface">Continue</button>
 ```
 
-Why: the named utility owns the complete treatment and composes every project-owned declaration through Tailwind.
+Why: canvas and ink CSS variables are used only by `primary-surface`, and the repeated combination has one named owner.

package/docs/styling-guide/styling-guide.md

@@ -1,17 +1,14 @@
 # Styling Guide
 
-This guide keeps component styling predictable without making consumers learn a component's DOM or a project's CSS internals. Use it whenever you add or change UI styling.
+This guide keeps component styling predictable without making consumers learn a component's DOM or a project's CSS internals. It applies whenever UI styling is added or changed.
 
 ## How To Style a Component
 
-Use this workflow when implementing a component or changing one of its visual treatments.
+Use this workflow when implementing a component or changing its appearance.
 
-1. Follow the [Tailwind Utility Rule](rules/tailwind-utility-rule.md) so ordinary, local styling stays visible beside the markup it affects.
-2. Follow the [Class Composition Rule](rules/class-composition-rule.md) so conditional and consumer-supplied classes merge predictably.
-3. Follow the [Component Variant Rule](rules/component-variant-rule.md) so supported internal appearances are a typed component API.
-4. Follow the [Color Role Naming Rule](rules/color-role-naming-rule.md) so color utilities state whether they supply a general color, a background, readable text, or a complete surface.
-5. Follow the [Theme and Utility Definition Rule](rules/theme-and-utility-definition-rule.md) so CSS-first theme tokens and custom utilities expose only the intended API.
-6. Follow the [Theme Token Rule](rules/theme-token-rule.md) so application chrome, content visuals, and shared measurements use the right kind of value.
-7. Follow the [Global Style System Rule](rules/global-style-system-rule.md) so global CSS has one source of truth and a clear ownership boundary.
-8. Follow the [Style Placement Rule](rules/style-placement-rule.md) so reusable styling has one appropriate owner.
-9. Follow the [Component State Rule](rules/component-state-rule.md) so interaction, disabled, selected, loading, and error states stay coherent.
+1. Follow the [Global Stylesheet Rule](rules/global-stylesheet-rule.md) so one stylesheet entry point owns all of the project's global CSS.
+2. Follow the [Theme and Utility Definition Rule](rules/theme-and-utility-definition-rule.md) so CSS variables, Tailwind namespaces, and custom utilities expose only the intended API.
+3. Follow the [Arbitrary Value Rule](rules/arbitrary-value-rule.md) so values used for the project's styling use named utilities or tokens instead of literal arbitrary classes.
+4. Follow the [Class Composition Rule](rules/class-composition-rule.md) so conditional and consumer-supplied classes merge predictably.
+5. Follow the [Component Variant Rule](rules/component-variant-rule.md) so supported internal appearances are a typed component API.
+6. Follow the [Component UI State Rule](rules/component-ui-state-rule.md) so interaction, disabled, selected, loading, and error UI states stay coherent.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pasika",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Reusable agent setup package",
   "repository": {
     "type": "git",

package/docs/code-organization-guide/rules/native-prop-forwarding-rule.md

@@ -1,38 +0,0 @@
-# Native Prop Forwarding Rule
-
-When a `src/shared/` component renders the same intrinsic root element in every rendered result, a smaller custom prop interface can hide capabilities that consumers need. This rule preserves native props while allowing focused component-specific props.
-
-- A `src/shared/` component with the same intrinsic root element in every rendered result MUST include that element's native props in its props type.
-- A `src/shared/` component with the same intrinsic root element in every rendered result MUST forward unconsumed native props to that element.
-- A `src/shared/` component with the same intrinsic root element in every rendered result MAY add component-specific props alongside its native props.
-
-## Incorrect — Native Props Replaced
-
-```tsx
-// src/shared/button.tsx
-type ButtonProps = {
-  label: string;
-  onClick(): void;
-};
-
-export function Button({ label, onClick }: ButtonProps) {
-  return <button onClick={onClick}>{label}</button>;
-}
-```
-
-Why: the custom interface leaves out native button props such as `disabled`, `type`, and accessible labels.
-
-## Correct — Native Props Extended and Forwarded
-
-```tsx
-// src/shared/button.tsx
-type ButtonProps = React.ComponentProps<"button"> & {
-  loading?: boolean;
-};
-
-export function Button({ className, loading, disabled, ...props }: ButtonProps) {
-  return <button className={cn("inline-flex items-center", className)} disabled={disabled || loading} {...props} />;
-}
-```
-
-Why: the component forwards its unused native props while adding the `loading` state it needs.

package/docs/documentation-guide/_templates/reference.md

@@ -1,17 +0,0 @@
-# [Topic] Reference
-
-[1-2 short sentences naming exactly what readers can look up here and when they should use this reference.]
-
-[Single lookup content — table, glossary, hierarchy, catalog, or config block. Keep this branch only when the reference has exactly one lookup block; it has no section heading. Otherwise delete this branch and use one heading per lookup group below.]
-
-## [First Lookup Group Name]
-
-[1-2 short sentences explaining what this group contains and why it is included.]
-
-[Place this group's lookup content here.]
-
-## [Next Lookup Group Name]
-
-[1-2 short sentences explaining what this group contains and why it is included.]
-
-[Place this group's lookup content here. Repeat the heading, explanation, and lookup content for every remaining group; delete this multi-block branch when the reference has one lookup block.]

package/docs/styling-guide/rules/color-role-naming-rule.md

@@ -1,115 +0,0 @@
-# Color Role Naming Rule
-
-Color names should reveal what a utility is safe to do, while keeping broadly reusable colors pleasant to use. This rule makes background-only colors, readable text colors, and complete treatments distinct without adding ceremony to general-purpose colors.
-
-- A color that is intentionally reusable across background, text, border, ring, or other CSS properties MUST use its role name without a property suffix.
-- A color intended only for a background MUST use the `-canvas` suffix, and a color intended only for readable text MUST use the `-ink` suffix.
-- A `*-canvas` or `*-ink` value MUST remain a private CSS variable and be exposed only through its matching property-specific custom utility.
-- `base-canvas` and `base-ink` MUST be applied only by the document body or the project's global base layer as the default page pair.
-- A repeated canvas, ink, and related treatment MUST become a `surface-*` custom utility that owns the complete treatment.
-- A general-purpose color backed by runtime-selectable theme variables MUST use `@theme inline` so Tailwind utilities remain stable while values change.
-- A one-off background MAY use a `*-canvas` utility directly when it does not form a repeated named surface.
-
-## Incorrect — Property-Specific Colors Exposed Broadly
-
-```css
-@theme {
-  --color-primary-background: #d87943;
-  --color-primary-text: #ffffff;
-}
-```
-
-```tsx
-<main className="bg-page text-page-text" />
-<button className="bg-primary-background text-primary-text">Save</button>
-```
-
-Why: the names are inconsistent, the document defaults can be applied anywhere, and the repeated button treatment has no single owner.
-
-## Correct — Color Roles Expose Their Intended API
-
-```css
-:root {
-  --base-canvas: #ffffff;
-  --base-ink: #111827;
-  --primary: #d87943;
-  --primary-canvas: #d87943;
-  --primary-ink: #ffffff;
-}
-
-.dark {
-  --base-canvas: #111827;
-  --base-ink: #f9fafb;
-  --primary: #f1a06e;
-  --primary-canvas: #f1a06e;
-  --primary-ink: #111827;
-}
-
-@theme {
-  --*: initial;
-  --shadow-sm: 0 1px 2px rgb(0 0 0 / 0.15);
-}
-
-@theme inline {
-  --color-primary: var(--primary);
-}
-
-@utility bg-base-canvas {
-  @apply bg-(--base-canvas);
-}
-
-@utility text-base-ink {
-  @apply text-(--base-ink);
-}
-
-@utility bg-primary-canvas {
-  @apply bg-(--primary-canvas);
-}
-
-@utility text-primary-ink {
-  @apply text-(--primary-ink);
-}
-
-@utility surface-primary {
-  @apply bg-primary-canvas text-primary-ink shadow-sm;
-
-  &:hover {
-    @apply brightness-105;
-  }
-}
-
-@layer base {
-  body {
-    @apply bg-base-canvas text-base-ink;
-  }
-}
-```
-
-```tsx
-// `primary` is useful for more than one CSS property.
-<a className="text-primary" />
-<button className="surface-primary">Save</button>
-
-// This background is a one-off rather than a named surface.
-<aside className="bg-primary-canvas text-primary-ink" />
-```
-
-Why: general-purpose colors stay suffix-free, property-specific colors reveal their role, the page defaults have one owner, and the reusable primary treatment owns its colors and behavior together.
-
-## Promotion Path
-
-Promote styling only as its reuse or design meaning grows:
-
-```txt
-Tailwind utility -> theme color -> paired color -> surface utility -> component variant
-```
-
-## When To Create a Named Surface
-
-Create a named `surface-*` utility when one or more of these signals applies:
-
-- The combination repeats in multiple places.
-- The combination has a clear product or design meaning.
-- Designers refer to the combination as a named treatment.
-- The combination needs to stay consistent across components.
-- The treatment includes more than color, such as a border, hover state, or shadow.

package/docs/styling-guide/rules/component-state-rule.md

@@ -1,26 +0,0 @@
-# Component State Rule
-
-Visual state communicates whether a component can be used and what will happen when it is used. This rule keeps that feedback owned by the component rather than reconstructed by every caller.
-
-- A component MUST provide a visually distinguishable treatment for every state it supports, including hover, focus, active, disabled, selected, loading, and error states when applicable.
-- Components MUST keep state styling with the component or its variant definition when the state is intrinsic to its behavior.
-- Components SHOULD use native semantic elements and attributes so browser, keyboard, and assistive-technology behavior matches the visual state.
-- Components MAY accept state props when the state is controlled by their parent.
-
-## Incorrect — State Styled Only with Classes
-
-```tsx
-<Button className={isSaving ? "pointer-events-none opacity-50" : ""}>Save</Button>
-```
-
-Why: every caller has to reconstruct the saving or disabled treatment, and the button does not receive a semantic disabled state.
-
-## Correct — State Exposed Through Component Props
-
-```tsx
-<Button disabled={isSaving} loading={isSaving}>
-  Save
-</Button>
-```
-
-Why: the component owns its loading and disabled treatment through a stable API, and the same ownership applies to every other state it supports.

package/docs/styling-guide/rules/global-style-system-rule.md

@@ -1,63 +0,0 @@
-# Global Style System Rule
-
-Global CSS is the integration point for Tailwind registration, the project theme, base styles, and imported style domains. This rule keeps one active entry point and a predictable ownership order.
-
-- A repository MUST have one active global stylesheet that owns Tailwind registration and imports every global style domain it uses.
-- The global stylesheet MUST reset the default Tailwind theme and register the project's explicit theme values.
-- Static theme values MUST live directly in `@theme`, while selector-driven variable mappings MUST live in `@theme inline`.
-- Global CSS MUST be ordered as imports, Tailwind and custom-variant registration, theme definitions and selectors, custom utilities, base styles, keyframes, then unavoidable global selectors.
-- Imported global style domains MUST have one owner and MUST NOT duplicate theme values or utilities defined by another domain.
-
-## Incorrect — Global Styles Split Across Unrelated Files
-
-```css
-/* Theme values and component recipes compete across unrelated files. */
-.save-button {
-  @apply bg-primary;
-}
-
-@theme {
-  --color-primary: #7c3aed;
-}
-```
-
-Why: a component recipe sits globally beside an unreset theme, and the stylesheet does not establish a clear integration order.
-
-## Correct — One Global Stylesheet Owns the System
-
-```css
-@import "tailwindcss";
-
-@custom-variant dark (&:where(.dark, .dark *));
-
-@theme {
-  --*: initial;
-  --spacing: 0.25rem;
-}
-
-:root {
-  --base-canvas: #ffffff;
-  --base-ink: #111827;
-}
-
-.dark {
-  --base-canvas: #111827;
-  --base-ink: #ffffff;
-}
-
-@utility bg-base-canvas {
-  @apply bg-(--base-canvas);
-}
-
-@utility text-base-ink {
-  @apply text-(--base-ink);
-}
-
-@layer base {
-  body {
-    @apply bg-base-canvas text-base-ink;
-  }
-}
-```
-
-Why: one entry point registers Tailwind, resets the theme, defines selector-driven values, exposes intended utilities, and applies document defaults in a predictable order.

package/docs/styling-guide/rules/style-placement-rule.md

@@ -1,49 +0,0 @@
-# Style Placement Rule
-
-Every project-owned style needs one implementation owner. This rule decides whether styling belongs beside component markup, in a named custom utility, or behind an unavoidable global selector.
-
-- Single-use component styling MUST stay colocated in the component through Tailwind utility classes or a local class constant.
-- A reusable behavior or treatment that has a stable design meaning MUST become a named custom utility.
-- A third-party selector, rich-content selector, document-state selector, browser selector, or pseudo-element-heavy effect that controlled JSX cannot own MAY use an unavoidable global selector.
-- An unavoidable global selector MUST compose project-owned declarations with `@apply`.
-- Component recipes MUST NOT become global selectors merely to shorten markup.
-- Literal arbitrary values MUST NOT replace missing project tokens or named utilities in component markup.
-
-## Incorrect — Component Recipe Defined Globally
-
-```css
-/* globals.css */
-.settings-save-button {
-  @apply inline-flex rounded-lg px-3 py-2;
-}
-```
-
-Why: a one-off component recipe is separated from the markup that owns it and creates a global selector to maintain.
-
-## Correct — Single-Use Styling Kept with the Component
-
-```tsx
-<button className="inline-flex rounded-lg px-3 py-2">Save</button>
-```
-
-Why: the local treatment stays with its component, while global selectors remain reserved for markup or browser behavior that controlled JSX cannot own.
-
-## Incorrect — Raw Declarations in an Unavoidable Selector
-
-```css
-.external-player .controls {
-  display: none;
-}
-```
-
-Why: third-party markup justifies the global selector, but the project-owned declaration still bypasses Tailwind composition.
-
-## Correct — Global Selector Uses `@apply`
-
-```css
-.external-player .controls {
-  @apply hidden;
-}
-```
-
-Why: the global selector owns an unavoidable third-party boundary while its declaration stays inside the project's Tailwind system.

package/docs/styling-guide/rules/tailwind-utility-rule.md

@@ -1,48 +0,0 @@
-# Tailwind Utility Rule
-
-Utility classes are most useful when they describe a component's local layout and appearance directly beside the element they affect. This rule prevents abstractions from hiding simple styling decisions.
-
-- Component markup MUST use static Tailwind utility classes for local layout, spacing, typography, and straightforward visual styling.
-- Components MUST NOT construct Tailwind class names from runtime fragments such as `bg-${color}`.
-- Components MUST use the closest project token or built-in utility for a static design value.
-- Components MUST NOT use literal arbitrary-value classes such as `top-[13px]` or `text-[#50d71e]` for project-owned styling.
-- A missing static design value MUST become an explicit project token or a named custom utility instead of an arbitrary literal in markup.
-- A CSS custom property MAY use Tailwind's custom-property shorthand when a named utility intentionally exposes that property-specific value.
-
-## Incorrect — Tailwind Classes Constructed at Runtime
-
-```tsx
-<div className={`p-${spacing} bg-${tone}`} />
-```
-
-Why: the class scanner cannot reliably see runtime-built utility names, and the available styles depend on runtime string construction.
-
-## Correct — Static Tailwind Classes
-
-```tsx
-<div className="bg-muted p-4" />
-```
-
-Why: the utilities are statically discoverable and show the element's local treatment where it is rendered.
-
-## Incorrect — Literal Arbitrary Design Value
-
-```tsx
-<div className="top-[13px]" />
-```
-
-Why: the design value is hidden in markup and cannot be tracked as part of the project's explicit token set.
-
-## Correct — Explicit Project Token
-
-```css
-@theme {
-  --spacing-floating-offset: 0.8125rem;
-}
-```
-
-```tsx
-<div className="top-floating-offset" />
-```
-
-Why: the named token makes the static design value searchable and gives every consumer one stable utility.

package/docs/styling-guide/rules/theme-token-rule.md

@@ -1,32 +0,0 @@
-# Theme Token Rule
-
-Application chrome must remain themeable, while artwork, user content, data, and faithful external visuals may carry color as content. This rule gives shared interface decisions semantic names without turning content colors into interface tokens.
-
-- Application chrome MUST use semantic project tokens and readable canvas/ink pairs.
-- Shared interface colors, surfaces, borders, typography roles, and reusable measurements MUST use semantic project tokens.
-- Components MUST NOT use palette utilities or literal colors for ordinary navigation, forms, dialogs, controls, status feedback, or focus treatment when a semantic role exists.
-- A new semantic token MUST represent a recurring interface meaning that existing roles cannot express.
-- Token names SHOULD describe purpose rather than a palette value or one component's implementation.
-- Content, artwork, user-selected media, data visualization, and faithful third-party visual reproductions MAY use literal colors when color is part of the content itself.
-- Opacity modifiers SHOULD express interaction and layering differences without creating a new semantic token.
-
-## Incorrect — Palette Colors Used for Interface Controls
-
-```tsx
-<Button className="bg-purple-600 text-white hover:bg-purple-500">Save</Button>
-<input className="border-[#6b7280] focus:ring-[#7c3aed]" />
-```
-
-Why: ordinary controls are tied to palette and literal values instead of the project's semantic action, canvas, ink, border, and focus roles.
-
-## Correct — Semantic Tokens Used for Interface Controls
-
-```tsx
-<Button tone="primary">Save</Button>
-<input className="border-border focus-visible:ring-focus/50" />
-
-// A product preview preserves the external brand color as content.
-<ProductPreview brandColor="#1db954" />
-```
-
-Why: ordinary interface styling uses the component API and semantic roles, while the faithful external visual retains the content color that defines it.