pasika 0.1.6 → 0.2.0

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

@@ -1,125 +0,0 @@
-# Component Variant Rule
-
-`cva` is Class Variance Authority, a helper for defining a component's visual options and deriving their TypeScript API. `cn` handles a standalone boolean choice without creating a variant matrix.
-
-- A component that lets callers choose visual options MUST define them with `cva`.
-- A component's variant prop types MUST be derived from its `cva` definition with `VariantProps` rather than manually duplicated unions.
-- A boolean prop that changes appearance MUST use conditional `cn()` when it only adds or removes one standalone class treatment.
-- A boolean prop that changes appearance MUST use a CVA variant when both boolean values have explicit treatments or when the boolean participates in a compound variant.
-
-## 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: "primary-surface",
-      danger: "danger-surface",
-    },
-  },
-  defaultVariants: {
-    size: "sm",
-    tone: "primary",
-  },
-});
-
-type ButtonProps = React.ComponentProps<"button"> & VariantProps<typeof buttonVariants>;
-
-export 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 Variant Added to CVA
-
-```tsx
-const buttonVariants = cva("inline-flex", {
-  variants: {
-    elevated: {
-      true: "shadow-md",
-      false: "",
-    },
-  },
-});
-```
-
-Why: one boolean variant merely adds a standalone treatment and has no compound relationship, so CVA adds configuration without a styling matrix.
-
-## Correct — Standalone Boolean Variant Uses `cn`
-
-```tsx
-<button className={cn(buttonVariants({ size, tone }), elevated && "shadow-md", className)} />
-```
-
-Why: the named appearance choices stay in CVA while the independent boolean variant remains a direct conditional class.
-
-## Incorrect — Compound Boolean Variant Styling Split Across Conditions
-
-```tsx
-<button
-  className={cn(
-    buttonVariants({ size }),
-    square && "justify-center",
-    square && size === "sm" && "w-8 px-0",
-    square && size === "lg" && "w-11 px-0",
-  )}
-/>
-```
-
-Why: the boolean variant changes treatment according to another variant, but the styling matrix is spread across conditional expressions outside CVA.
-
-## Correct — Boolean Variant with Compound Styling Uses CVA
-
-```tsx
-const buttonVariants = cva("inline-flex", {
-  variants: {
-    size: {
-      sm: "h-8 px-3",
-      lg: "h-11 px-5",
-    },
-    square: {
-      true: "justify-center",
-      false: "justify-start",
-    },
-  },
-  compoundVariants: [
-    {
-      size: "sm",
-      square: true,
-      className: "w-8 px-0",
-    },
-    {
-      size: "lg",
-      square: true,
-      className: "w-11 px-0",
-    },
-  ],
-});
-```
-
-Why: both boolean values have explicit treatment and the square appearance changes by size, so CVA owns the complete styling matrix.

package/docs/styling-guide/rules/global-stylesheet-rule.md

@@ -1,67 +0,0 @@
-# Global Stylesheet Rule
-
-Use the global stylesheet to define Tailwind, the shared theme, and base styles. This rule keeps all of the project's global CSS in one entry point and ordered predictably.
-
-- A repository MUST have one global stylesheet entry point that registers Tailwind.
-- The project's global CSS MUST live in the global stylesheet entry point and MUST NOT be imported from another file.
-- The global stylesheet MUST reset Tailwind's default theme with `--*: initial`.
-- Every value used for the project's styling MUST be defined as a CSS variable in `:root`, even when no theme selector overrides it. A Tailwind theme variable MUST reference that CSS variable through `@theme inline`.
-- Style declarations added by the project inside global selectors MUST use `@apply`.
-- The global stylesheet MUST order imports, `@custom-variant` definitions, `:root` variables and the selectors that override them, `@theme` definitions, custom utilities, base styles, and keyframes in that order.
-- The global base layer MUST apply `base-canvas` and `base-ink` to the document body as the default page pair.
-
-## Incorrect — Global Styles Split Across Unrelated Files
-
-```css
-/* globals.css */
-@import "tailwindcss";
-
-@theme {
-  --spacing: 0.25rem;
-}
-
-/* editor.css */
-@import "tailwindcss";
-
-@theme {
-  --font-editor: Georgia, serif;
-}
-```
-
-Why: Tailwind and theme definitions are split across competing global entry points, so neither file clearly owns the system.
-
-## Correct — One Global Stylesheet Owns the System
-
-```css
-@import "tailwindcss";
-
-:root {
-  --spacing: 0.25rem;
-  --base-canvas: #ffffff;
-  --base-ink: #111827;
-}
-
-@theme {
-  --*: initial;
-}
-
-@theme inline {
-  --spacing: var(--spacing);
-}
-
-@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, defines the shared system, and applies document defaults in a predictable order.

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

@@ -1,86 +0,0 @@
-# Theme and Utility Definition Rule
-
-This rule decides when styling stays with one component or becomes a shared utility, and how project values are exposed through Tailwind.
-
-- 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 — Property-Specific Color Exposed Broadly
-
-```css
-:root {
-  --color-header-ink: #111827;
-}
-
-@theme inline {
-  --color-header-ink: var(--color-header-ink);
-}
-```
-
-```tsx
-<h1 className="text-header-ink">Title</h1>
-```
-
-Why: registering a text-only color in `--color-*` also creates unintended background, border, ring, and other color utilities.
-
-## Correct — Property-Specific Utility
-
-```css
-:root {
-  --header-ink: #111827;
-}
-
-@utility text-header-ink {
-  @apply text-(--header-ink);
-}
-```
-
-```tsx
-// SiteHeader.tsx
-<h1 className="text-header-ink">Title</h1>
-
-// PageHeader.tsx
-<h2 className="text-header-ink">Settings</h2>
-```
-
-Why: both components use the same text-only color, so one named text utility owns it without creating background, border, or ring utilities.
-
-## Incorrect — Property-Specific Colors Exposed Broadly
-
-```css
-@theme {
-  --color-primary-canvas: #d87943;
-  --color-primary-ink: #ffffff;
-}
-```
-
-```tsx
-<button className="bg-primary-canvas text-primary-ink">Save</button>
-<button className="bg-primary-canvas text-primary-ink">Continue</button>
-```
-
-Why: property-specific colors are exposed as broad Tailwind colors, and the repeated combination has no named owner.
-
-## Correct — Color Roles Expose Their Intended API
-
-```css
-:root {
-  --primary-canvas: #d87943;
-  --primary-ink: #ffffff;
-}
-
-@utility primary-surface {
-  @apply bg-(--primary-canvas) text-(--primary-ink);
-}
-```
-
-```tsx
-<button className="primary-surface">Save</button>
-<button className="primary-surface">Continue</button>
-```
-
-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,14 +0,0 @@
-# Styling Guide
-
-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 its appearance.
-
-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.