pasika 0.1.0 → 0.1.4

package/docs/shadcn-theme.md

@@ -0,0 +1,121 @@
+# shadcn Theme
+
+Use this profile when a project uses shadcn UI tokens as its theme baseline.
+
+## File structure
+
+Read the theme file by section:
+
+1. `@theme inline` exposes CSS variables to Tailwind utilities.
+2. `:root` defines light-mode token values.
+3. `.dark` defines dark-mode token values.
+4. `@layer base` applies default page, border, and outline styling.
+
+Component authors write utilities such as `bg-primary`, `text-primary-foreground`, and `rounded-lg`. Tailwind resolves those utilities through the tokens registered in `@theme inline`. Do not write generated CSS by hand.
+
+## Registered Tailwind tokens
+
+`@theme inline` maps project CSS variables to Tailwind token names. The categories below mirror the groups in a standard shadcn `globals.css`.
+
+| Category | CSS variables | Utility examples |
+|---|---|---|
+| Page defaults | `--color-background`, `--color-foreground` | `bg-background`, `text-foreground` |
+| Content surfaces | `--color-card`, `--color-card-foreground`, `--color-popover`, `--color-popover-foreground` | `bg-card text-card-foreground`, `bg-popover text-popover-foreground` |
+| Action and state surfaces | `--color-primary`, `--color-primary-foreground`, `--color-secondary`, `--color-secondary-foreground`, `--color-muted`, `--color-muted-foreground`, `--color-accent`, `--color-accent-foreground`, `--color-destructive` | `bg-primary text-primary-foreground`, `bg-muted text-muted-foreground`, `bg-destructive text-white` |
+| Borders, form fields, focus | `--color-border`, `--color-input`, `--color-ring` | `border`, `border-input`, `ring-ring`, `outline-ring/50` |
+| Charts | `--color-chart-1` through `--color-chart-5` | `bg-chart-1`, `text-chart-2` |
+| Sidebar | `--color-sidebar`, `--color-sidebar-foreground`, `--color-sidebar-primary`, `--color-sidebar-primary-foreground`, `--color-sidebar-accent`, `--color-sidebar-accent-foreground`, `--color-sidebar-border`, `--color-sidebar-ring` | `bg-sidebar`, `text-sidebar-foreground`, `border-sidebar-border` |
+| Radius | `--radius-sm`, `--radius-md`, `--radius-lg`, `--radius-xl`, `--radius-2xl`, `--radius-3xl`, `--radius-4xl` | `rounded-sm`, `rounded-md`, `rounded-lg`, `rounded-xl`, `rounded-2xl`, `rounded-3xl`, `rounded-4xl` |
+
+## Value tokens
+
+`:root` and `.dark` define the actual values for the same semantic tokens. The token names stay stable; only the values change between theme modes.
+
+### Page defaults
+
+| Token | Use |
+|---|---|
+| `background` | App/page background |
+| `foreground` | Default app text |
+
+Use together as `bg-background text-foreground`.
+
+### Content surfaces
+
+| Token pair | Use |
+|---|---|
+| `card` / `card-foreground` | Card or elevated surface content |
+| `popover` / `popover-foreground` | Floating surfaces like menus, tooltips, dialogs |
+
+Use as `bg-card text-card-foreground` and `bg-popover text-popover-foreground`.
+
+### Action and state surfaces
+
+| Token pair | Use |
+|---|---|
+| `primary` / `primary-foreground` | Main action or selected/high-emphasis filled state |
+| `secondary` / `secondary-foreground` | Supporting action or lower-emphasis filled state |
+| `muted` / `muted-foreground` | Subtle surface and de-emphasized content |
+| `accent` / `accent-foreground` | Transient hover, active, or current-row surface |
+| `destructive` | Destructive action or error surface |
+
+Fresh shadcn components use fixed white foreground on destructive filled surfaces:
+
+```tsx
+<Button className="bg-destructive text-white" />
+```
+
+### Borders, form fields, and focus
+
+| Token | shadcn use | Utility examples |
+|---|---|---|
+| `border` | Default borders and separators | `border`, `border-b` |
+| `input` | Form-control border color and input-like surface treatment | `border-input`, `dark:bg-input/30`, `dark:border-input`, `dark:hover:bg-input/50` |
+| `ring` | Focus border, ring, and outline color | `focus-visible:border-ring`, `focus-visible:ring-ring/50`, `focus-visible:outline-ring`, `outline-ring/50` |
+
+The base layer already applies `border-border` and `outline-ring/50`; component code usually needs only the structural border utility (`border`, `border-b`, etc.) unless it is using another border role or overriding a competing border-color class.
+
+### Charts
+
+`chart-1` through `chart-5` are palette slots for charts and data visualizations. They are not app surface tokens and do not imply foreground pairs.
+
+### Sidebar
+
+Sidebar tokens are scoped versions of the same shadcn roles for sidebar UI:
+
+- `sidebar` / `sidebar-foreground`
+- `sidebar-primary` / `sidebar-primary-foreground`
+- `sidebar-accent` / `sidebar-accent-foreground`
+- `sidebar-border`
+- `sidebar-ring`
+
+### Radius
+
+`radius` is the base radius value. `@theme inline` derives Tailwind radius utilities from it.
+
+## Base layer
+
+shadcn applies default app chrome in `@layer base`:
+
+```css
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+  }
+  body {
+    @apply bg-background text-foreground;
+  }
+}
+```
+
+The base layer applies `border-border` and `outline-ring/50` globally. Plain `border`, `border-b`, etc. inherit the default border color when no competing border-color class is present. Add an explicit border color for another role, such as `border-input`, `border-primary`, `border-destructive`, or `focus-visible:border-ring`, or when overriding a component variant such as `border-transparent`.
+
+## Adding tokens
+
+Treat fresh shadcn tokens as the baseline. Add project-specific tokens only when the project explicitly adopts an extension beyond shadcn defaults, and document that extension outside this baseline profile.
+
+## Update trigger
+
+Re-check this document when the [shadcn changelog](https://ui.shadcn.com/docs/changelog) changes the theme token contract, default theme CSS, or generated component styling conventions.
+
+When re-checking, verify the affected claims against current shadcn docs and generated registry components before editing this document.

package/docs/styling-guide/rules/class-composition-rule.md

@@ -0,0 +1,32 @@
+# Class Composition Rule
+
+Class conditions and caller overrides need one consistent merge point so ordering stays understandable and conflicting Tailwind utilities resolve correctly.
+
+- Components MUST use `cn` or the project's equivalent class-merging helper for conditional classes and a consumer-provided `className`.
+- Components MUST NOT concatenate class strings with template literals or `+` when any part is conditional.
+- A consumer-provided `className` MUST contain only outer-layout utilities: margins, width constraints, permitted height constraints, and flex or grid item placement.
+- Permitted height constraints MUST be limited to `h-full`, `h-auto`, `min-h-*`, and `max-h-*`; fixed component heights MUST use a typed component API or an external wrapper.
+- A consumer-provided `className` MUST NOT change padding, internal gaps, fixed height, colors, typography, borders, radius, shadows, effects, positioning, inset, or z-index.
+- A component MUST expose supported internal appearance and fixed-size choices through typed props rather than consumer classes.
+- Components SHOULD group long static class lists by concern inside `cn`.
+- Components MAY keep a short, fully static `className` string inline.
+
+## Incorrect — Conditional Classes Concatenated Manually
+
+```tsx
+<button className={"rounded px-3 " + (active ? "bg-primary" : "bg-muted")} />
+```
+
+Why: the condition and merge order are embedded in a string expression, which becomes difficult to extend with consumer overrides.
+
+## Correct — Conditional Classes Merged with `cn`
+
+```tsx
+export default function Card({ className, ...props }: CardProps): React.JSX.Element {
+  return <article className={cn("surface-card rounded-lg p-4", className)} {...props} />;
+}
+
+<Card className="w-full max-w-lg self-center" />;
+```
+
+Why: every class source is explicit, and a consumer can add outer layout such as `w-full max-w-lg self-center` without reconstructing the card's internal treatment.

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

@@ -0,0 +1,115 @@
+# 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

@@ -0,0 +1,26 @@
+# 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/component-variant-rule.md

@@ -0,0 +1,128 @@
+# Component Variant Rule
+
+When callers choose between a component's visual appearances, the styling definition and TypeScript API need one source of truth. This rule uses CVA for named choices and reserves `cn` for standalone boolean conditions.
+
+- A component that lets callers choose between named visual appearances MUST define those choices with `cva`.
+- Component variant prop types MUST be derived with `VariantProps<typeof componentVariants>`.
+- Component props MUST NOT manually duplicate a union already defined by the CVA configuration.
+- A boolean appearance input MUST use conditional `cn()` when it only adds or removes one standalone class treatment.
+- A boolean appearance input MUST use a CVA variant when both boolean values have explicit treatments or when the boolean participates in a compound variant.
+- A component MUST NOT expose separate class-name props for internal elements to vary their appearance.
+- A component MAY expose structured content slots when callers need to provide content rather than alter internal styling.
+
+## Incorrect — Variant Union Duplicated by Hand
+
+```tsx
+const buttonVariants = cva("inline-flex items-center", {
+  variants: {
+    size: {
+      sm: "h-8 px-3",
+      lg: "h-11 px-5",
+    },
+  },
+});
+
+type ButtonProps = React.ComponentProps<"button"> & {
+  size?: "sm" | "lg";
+};
+```
+
+Why: the accepted `size` values now live in both CVA and a handwritten prop union, so either side can change without the other.
+
+## Correct — Props Derived from CVA
+
+```tsx
+const buttonVariants = cva("inline-flex items-center", {
+  variants: {
+    size: {
+      sm: "h-8 px-3",
+      lg: "h-11 px-5",
+    },
+    tone: {
+      primary: "surface-primary",
+      danger: "surface-danger",
+    },
+  },
+  defaultVariants: {
+    size: "sm",
+    tone: "primary",
+  },
+});
+
+type ButtonProps = React.ComponentProps<"button"> & VariantProps<typeof buttonVariants>;
+
+export default function Button({ size, tone, className, ...props }: ButtonProps): React.JSX.Element {
+  return <button className={cn(buttonVariants({ size, tone }), className)} {...props} />;
+}
+```
+
+Why: the CVA definition owns the accepted values, defaults, and classes, while `VariantProps` derives the public TypeScript API from the same source.
+
+## Incorrect — Standalone Boolean Added to CVA
+
+```tsx
+const buttonVariants = cva("inline-flex", {
+  variants: {
+    loading: {
+      true: "cursor-wait opacity-70",
+      false: "",
+    },
+  },
+});
+```
+
+Why: one boolean merely adds a standalone treatment and has no compound relationship, so CVA adds configuration without a styling matrix.
+
+## Correct — Standalone Boolean Uses `cn`
+
+```tsx
+<button className={cn(buttonVariants({ size, tone }), loading && "cursor-wait opacity-70", className)} />
+```
+
+Why: the named appearance choices stay in CVA while the independent boolean remains a direct conditional class.
+
+## Incorrect — Compound Boolean Styling Split Across Conditions
+
+```tsx
+<button
+  className={cn(
+    buttonVariants({ tone }),
+    loading && "cursor-wait",
+    loading && tone === "primary" && "surface-primary-loading",
+    loading && tone === "danger" && "surface-danger-loading",
+  )}
+/>
+```
+
+Why: the boolean changes treatment according to another variant, but the styling matrix is spread across conditional expressions outside CVA.
+
+## Correct — Boolean with Compound Styling Uses CVA
+
+```tsx
+const buttonVariants = cva("inline-flex", {
+  variants: {
+    tone: {
+      primary: "surface-primary",
+      danger: "surface-danger",
+    },
+    loading: {
+      true: "cursor-wait",
+      false: "cursor-default",
+    },
+  },
+  compoundVariants: [
+    {
+      tone: "primary",
+      loading: true,
+      className: "surface-primary-loading",
+    },
+    {
+      tone: "danger",
+      loading: true,
+      className: "surface-danger-loading",
+    },
+  ],
+});
+```
+
+Why: both boolean values have explicit treatment and loading changes by tone, so CVA owns the complete styling matrix.

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

@@ -0,0 +1,63 @@
+# 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

@@ -0,0 +1,49 @@
+# 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

@@ -0,0 +1,48 @@
+# 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.