pasika 0.1.4 → 0.2.0

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/component-variant-rule.md

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

@@ -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-and-utility-definition-rule.md

@@ -1,129 +0,0 @@
-# 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.
-
-- 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.
-
-## Incorrect — Default Theme Kept and Property-Specific Color Exposed Broadly
-
-```css
-@theme {
-  --color-header-ink: var(--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.
-
-## Correct — Custom Theme and Property-Specific Utility
-
-```css
-:root {
-  --header-ink: #111827;
-}
-
-@theme {
-  --*: initial;
-  --spacing: 0.25rem;
-  --font-body: Inter, sans-serif;
-}
-
-@utility text-header {
-  @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;
-}
-
-@theme inline {
-  --color-primary: var(--primary);
-}
-```
-
-Why: generated color utilities reference the selector-driven runtime value directly.
-
-## Incorrect — Treatment Split Across Utilities and Raw Declarations
-
-```css
-@utility surface-primary {
-  background-color: var(--primary-canvas);
-}
-
-@utility surface-primary-hover {
-  background-color: var(--primary-canvas-hover);
-}
-```
-
-```tsx
-<button className="surface-primary hover:surface-primary-hover">Save</button>
-```
-
-Why: the treatment is split across public utilities, its state is reconstructed in markup, and project-owned declarations bypass Tailwind composition.
-
-## Correct — Complete Treatment Composed with `@apply`
-
-```css
-@utility surface-primary {
-  @apply rounded-md bg-(--primary-canvas) px-3 py-2 text-(--primary-ink);
-
-  &:hover {
-    @apply bg-(--primary-canvas-hover);
-  }
-
-  &:focus-visible {
-    @apply outline-2 outline-(--focus-ring);
-  }
-}
-```
-
-```tsx
-<button className="surface-primary">Save</button>
-```
-
-Why: the named utility owns the complete treatment and composes every project-owned declaration through Tailwind.

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.

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

@@ -1,17 +0,0 @@
-# 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.
-
-## How To Style a Component
-
-Use this workflow when implementing a component or changing one of its visual treatments.
-
-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.