pasika 0.1.6 → 0.3.0

package/docs/documentation-guide/rules/reference-creation-rule.md

@@ -1,132 +0,0 @@
-# Reference Creation Rule
-
-References without a consistent creation process scatter lookup material. This rule defines how to create a Reference document.
-
-- Reference file names MUST match the document title in kebab-case and use the `-reference` suffix (e.g., `foo-reference.md`).
-- A Reference MUST NOT link to Rules, Guides, or other References.
-- A Reference MUST NOT use RFC 2119 vocabulary (`MUST`, `MUST NOT`, `SHOULD`, `SHOULD NOT`, `MAY`), because lookup material describes what exists rather than imposing requirements.
-- A Reference overview and the overview of each headed lookup block MUST contain one or two short sentences.
-- A Reference with a single lookup block MUST NOT add a section heading for it.
-- A Reference with two or more lookup blocks MUST add a section heading for every block, including the first.
-
-## Incorrect — Reference Links to Another Document
-
-```markdown
-- See the [Naming Rule](../rules/naming-rule.md) for the file naming conventions.
-```
-
-Why: reference body contains a reference to another Rule.
-
-## Correct — Reference States the Lookup Fact Directly
-
-```markdown
-- File names are kebab-case, match the document title, and have a `-reference` suffix.
-```
-
-Why: reference states lookup content directly without linking to its source.
-
-## Incorrect — Reference Uses Requirement Vocabulary
-
-```markdown
-| Layer | Contents                                          |
-| ----- | ------------------------------------------------- |
-| `app` | Routing files only — a route MUST NOT hold a util |
-```
-
-Why: the cell carries RFC 2119 vocabulary, so a Reference asserts a requirement that only a Rule can own, and the same constraint ends up stated in two documents.
-
-## Correct — Reference Describes Existing Content
-
-```markdown
-| Layer | Contents           |
-| ----- | ------------------ |
-| `app` | Routing files only |
-```
-
-Why: the cell describes what the layer holds, leaving the requirement to the Rule that owns it.
-
-## Incorrect — Single Lookup Block Has a Heading
-
-```markdown
-# Option Reference
-
-Use this reference to choose between the two supported project sizes when starting a new initiative.
-
-## Options
-
-Pick the size that matches the team's headcount and timeline.
-
-| Option | Use Case       |
-| ------ | -------------- |
-| A      | Small projects |
-| B      | Large projects |
-```
-
-Why: section heading is unnecessary and forces a duplicated intro covering what the reference is for and what the group contains.
-
-## Correct — Single Lookup Block Has No Heading
-
-```markdown
-# Option Reference
-
-Use this reference to choose between the two supported project sizes when starting a new initiative.
-
-| Option | Use Case       |
-| ------ | -------------- |
-| A      | Small projects |
-| B      | Large projects |
-```
-
-Why: single lookup block sits directly under the intro without a heading.
-
-## Incorrect — First of Multiple Lookup Blocks Has No Heading
-
-```markdown
-# Option Reference
-
-Use this reference to look up the supported project sizes and the review gates each one requires.
-
-| Option | Use Case       |
-| ------ | -------------- |
-| A      | Small projects |
-| B      | Large projects |
-
-## Review Gates
-
-Each size carries a different approval bar.
-
-| Option | Approvals |
-| ------ | --------- |
-| A      | 1         |
-| B      | 2         |
-```
-
-Why: the reference has two lookup blocks but only the second is headed, so the first table reads as part of the intro and cannot be scanned or linked as a group of its own.
-
-## Correct — Every Lookup Block Has a Heading
-
-```markdown
-# Option Reference
-
-Use this reference to look up the supported project sizes and the review gates each one requires.
-
-## Project Sizes
-
-Pick the size that matches the team's headcount and timeline.
-
-| Option | Use Case       |
-| ------ | -------------- |
-| A      | Small projects |
-| B      | Large projects |
-
-## Review Gates
-
-Each size carries a different approval bar.
-
-| Option | Approvals |
-| ------ | --------- |
-| A      | 1         |
-| B      | 2         |
-```
-
-Why: both lookup blocks are headed, so they read as peers and each is independently scannable and linkable.

package/docs/documentation-guide/rules/rule-creation-rule.md

@@ -1,81 +0,0 @@
-# Rule Creation Rule
-
-Rules without a consistent creation process invent their own structure and enforcement language. This rule defines how to create a Rule document.
-
-- Rule file names MUST match the document title in kebab-case and use the `-rule` suffix (e.g., `foo-rule.md`).
-- A Rule MUST contain at least one bullet point that uses [RFC 2119 vocabulary](https://datatracker.ietf.org/doc/html/rfc2119) (`MUST`, `MUST NOT`, `SHOULD`, `SHOULD NOT`, `MAY`).
-- RFC 2119 vocabulary MUST appear only in bullet points, so the bullet list is the single place a requirement is stated.
-- Prose outside bullet points — intros, `Why:` explanations, table cells, and code comments — MUST restate a requirement in plain language instead of repeating RFC 2119 vocabulary.
-- `MUST` MUST mean required.
-- `MUST NOT` MUST mean forbidden.
-- `SHOULD` MUST mean recommended, with exceptions possible.
-- `SHOULD NOT` MUST mean discouraged, with exceptions possible.
-- `MAY` MUST mean optional.
-- A Rule MUST contain at least one Incorrect/Correct pair.
-- A Rule MAY contain multiple Incorrect/Correct pairs.
-- An Incorrect/Correct pair MUST add a concise description after an em dash in both headings, so readers can scan the examples by decision.
-- A Rule MUST NOT link to References, Guides, or other Rules.
-
-## Incorrect — Lowercase Requirement Words
-
-```markdown
-- Authors must remove unused sections.
-- New docs should use the -rule suffix.
-```
-
-Why: lower-case "must" and "should" do not carry RFC 2119 meaning.
-
-## Correct — RFC 2119 Requirement Words
-
-```markdown
-- Authors MUST remove unused sections.
-- New docs SHOULD use the -rule suffix.
-```
-
-Why: uppercase keywords carry their canonical RFC 2119 meaning.
-
-## Incorrect — Rule Links to a Reference
-
-```markdown
-- Rule bodies MUST follow the guidance in the [Vocabulary Reference](../references/vocabulary-reference.md).
-```
-
-Why: rule contains a reference to another Reference.
-
-## Correct — Rule States Its Vocabulary Directly
-
-```markdown
-- Rule bodies MUST use RFC 2119 vocabulary: MUST, MUST NOT, SHOULD, SHOULD NOT, or MAY.
-```
-
-Why: rule states requirements directly without referencing other docs.
-
-## Incorrect — Requirement Repeated in an Explanation
-
-```markdown
-- A helper file MUST use named exports.
-
-## Incorrect — Default Export
-
-// helper.ts
-export default function sum(a, b) {}
-
-Why: a helper file MUST use named exports, so `export default` is not allowed here.
-```
-
-Why: the explanation repeats the bullet's requirement word, so the requirement now lives in two places and a later edit can leave the bullet and the explanation disagreeing about what is required.
-
-## Correct — Requirement Explained in Plain Language
-
-```markdown
-- A helper file MUST use named exports.
-
-## Incorrect — Default Export
-
-// helper.ts
-export default function sum(a, b) {}
-
-Why: helper files use named exports only, so `export default` does not belong here.
-```
-
-Why: the bullet is the only place the requirement is stated, and the explanation describes the example in plain language.

package/docs/documentation-guide/rules/template-usage-rule.md

@@ -1,49 +0,0 @@
-# Template Usage Rule
-
-Authoring without a template makes every doc invent its own title, orientation, and section shape. This rule keeps new docs predictable. Templates for each document kind live in `../_templates/`.
-
-- Authors MUST start from the template that matches the chosen document kind and structure.
-- Authors MUST replace each bracketed prompt with the final title, explanation, step, or lookup content it asks for.
-- Authors MUST delete template branches that do not apply to the document being written.
-- Documentation support assets MAY live in folders whose names start with an underscore.
-
-## Incorrect — Template Prompts and Unused Branches Kept
-
-```markdown
-# Example Guide
-
-[1-2 short sentences explaining the underlying idea behind this guide and why it matters.]
-
-## How To Do Something
-
-[What does this accomplish? When should it run?]
-
-1. [Step 1]
-2. [Step 2]
-
-## How To Another Workflow
-
-[What does this accomplish? When should it run?]
-
-1. [Step 1]
-2. [Step 2]
-```
-
-Why: committed doc still contains bracketed prompts, and the unused "Another Workflow" section was not deleted.
-
-## Correct — Template Prompts Replaced and Unused Branches Removed
-
-```markdown
-# Example Guide
-
-This guide shows how to do something useful. It matters because doing it wrong breaks the build.
-
-## How To Do Something
-
-Run this before every release.
-
-1. Check the config.
-2. Run the deploy script.
-```
-
-Why: all bracketed prompts are replaced, unused template branches are deleted, and no leftover brackets remain.

package/docs/shadcn-theme.md

@@ -1,121 +0,0 @@
-# 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/arbitrary-value-rule.md

@@ -1,31 +0,0 @@
-# Arbitrary Value Rule
-
-Literal arbitrary-value classes hide values used for the project's styling in component code. This rule requires every such value to have a named utility or token.
-
-- Components MUST NOT use arbitrary-value classes for project styling. They MUST use an existing Tailwind or project utility, or define a project token or custom utility first.
-
-## Incorrect — Literal Arbitrary Radius
-
-```tsx
-<button className="rounded-[13px]">Save</button>
-```
-
-Why: the design value is hidden in markup and cannot be tracked as part of the project's explicit token set.
-
-## Correct — Named Radius Token
-
-```css
-:root {
-  --radius-md: 0.375rem;
-}
-
-@theme inline {
-  --radius-md: var(--radius-md);
-}
-```
-
-```tsx
-<button className="rounded-md">Save</button>
-```
-
-Why: the named value makes the radius searchable and exposes the matching Tailwind radius utility.

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

@@ -1,52 +0,0 @@
-# Class Composition Rule
-
-`cn` is the project's helper for combining conditional classes and resolving conflicting Tailwind utilities. It gives conditional classes and a passed `className` one predictable merge point.
-
-- Components MUST use `cn` or the project's equivalent class-merging helper for conditional classes and a `className` passed to the component.
-- Components MUST NOT concatenate class strings with template literals or `+` when any part is conditional.
-- A `className` passed to a component MUST contain only outer-layout utilities: margins, sizing, flex or grid item placement, and `z-index`.
-- A component MUST expose its supported appearance and size variants through typed props, not through a passed `className` or separate class-name props for internal elements.
-- A static class list with more than five class names MUST use `cn` with multiple string literals, each grouped by styling concern and containing no more than five class names.
-
-## 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 function Card({ className, ...props }: CardProps): React.JSX.Element {
-  return <article className={cn("card-surface 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.
-
-## Incorrect — Long Static Class Literal
-
-```tsx
-<article className="rounded-lg border border-border bg-card px-6 py-4 shadow-sm transition-shadow hover:shadow-md" />
-```
-
-Why: one static literal contains more than five class names, so its styling concerns are difficult to scan.
-
-## Correct — Static Classes Grouped in `cn`
-
-```tsx
-<article
-  className={cn(
-    "rounded-lg border border-border",
-    "bg-card shadow-sm",
-    "px-6 py-4",
-    "transition-shadow hover:shadow-md",
-  )}
-/>
-```
-
-Why: each literal contains at most five class names and groups one styling concern.

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

@@ -1,53 +0,0 @@
-# Component UI 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 own a distinguishable appearance for every UI state it supports.
-- A component MUST use Tailwind "state variants" when they can express a supported UI state.
-- Components MUST use native semantic elements and attributes and MUST NOT use custom equivalents.
-
-## 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
-import { cn } from "@/utils/cn";
-
-type ButtonProps = {
-  children: React.ReactNode;
-  disabled?: boolean;
-  loading?: boolean;
-};
-
-export function Button({ children, disabled = false, loading = false }: ButtonProps): React.JSX.Element {
-  const isUnavailable = disabled || loading;
-
-  return (
-    <button
-      aria-busy={loading}
-      className={cn(
-        "rounded px-3",
-        "hover:opacity-90 focus-visible:outline-2",
-        "disabled:cursor-not-allowed disabled:opacity-50",
-        "aria-busy:animate-pulse",
-      )}
-      disabled={isUnavailable}
-      type="button"
-    >
-      {loading ? "Saving…" : children}
-    </button>
-  );
-}
-
-<Button loading={isSaving}>
-  Save
-</Button>
-```
-
-Why: `Button` uses native disabled and ARIA busy attributes with Tailwind state variants, while callers express only loading through its typed API.

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.