pasika 0.1.6 → 0.2.0

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

@@ -1,113 +0,0 @@
-# Guide Creation Rule
-
-Guides without a consistent creation process invent their own structure. This rule defines how to create a Guide document.
-
-- Each How To step MUST be concise and use one sentence.
-- A Guide MAY reference Rules, References, and other Guides.
-- A Guide overview MUST contain one or two short descriptive sentences about the guide's scope and purpose, and MUST NOT contain instructions or links to other documentation.
-- Each How To step MUST link at most one documentation file total, whether that file is a Rule, Reference, or Guide.
-- When a step links a Rule, Reference, or Guide, the step MUST name the concrete decision or result the reader will have after reading it.
-- A step that links another Guide MUST link directly to the relevant How To section.
-- How To sections MUST NOT nest inside other How To sections.
-- Guide file names MUST match the document title in kebab-case and use the `-guide` suffix (e.g., `foo-guide.md`).
-- A Guide with private support files MUST become a folder named the same as its entry-point file, without the `.md` extension.
-- Private Rule files for a Guide MUST live in a `rules/` subfolder inside the Guide's folder.
-- Private Reference files for a Guide MUST live in a `references/` subfolder inside the Guide's folder.
-
-## Incorrect — Private Documents Mixed at the Guide Root
-
-```text
-feature-workflow-guide/
-├── feature-workflow-guide.md
-├── naming-rule.md
-└── option-reference.md
-```
-
-Why: mixed Markdown files turn the doc folder into an undifferentiated list once the doc grows.
-
-## Correct — Private Documents Grouped by Kind
-
-```text
-feature-workflow-guide/
-├── feature-workflow-guide.md
-├── rules/
-│   └── naming-rule.md
-└── references/
-    └── option-reference.md
-```
-
-Why: private support files stay colocated with the entry point while being grouped by document kind.
-
-## Incorrect — Step Links to Multiple Documents
-
-```markdown
-1. Follow the [Naming Rule](rules/naming-rule.md) and the [Layout Rule](rules/layout-rule.md) so the doc looks right.
-```
-
-Why: step links two Rules and does not name a concrete decision or result.
-
-## Correct — Step Links to One Document
-
-```markdown
-1. Follow the [Naming Rule](rules/naming-rule.md) so the doc has a predictable file name.
-```
-
-Why: step links one Rule and names the concrete result the reader will have.
-
-## Incorrect — Nested How To Section
-
-```markdown
-## How To Deploy
-
-1. Build the project.
-   ### How To Build
-   1. Run the build script.
-```
-
-Why: a How To section nests inside a step of another How To section.
-
-## Correct — Flat How To Sections
-
-```markdown
-## How To Deploy
-
-1. Follow [How To Build](#how-to-build) to build the project.
-
-## How To Build
-
-1. Run the build script.
-```
-
-Why: How To sections stay flat and reference each other via links.
-
-## Incorrect — Multi-Sentence Step
-
-```markdown
-1. First, check the configuration file. Then verify all required fields are present. After that, confirm none of the fields contain invalid values.
-```
-
-Why: step uses multiple sentences instead of one concise sentence.
-
-## Correct — Concise Step
-
-```markdown
-1. Run the config check script.
-```
-
-Why: step is one concise sentence with a concrete action.
-
-## Incorrect — Guide Link Omits Its How To Section
-
-```markdown
-1. Follow the [Build Guide](build-guide.md) to build the project.
-```
-
-Why: link points at a Guide file but does not anchor to a specific How To section, so the reader lands on the guide's introduction and has to search for the relevant workflow.
-
-## Correct — Guide Link Targets Its How To Section
-
-```markdown
-1. Follow [How To Build](build-guide.md#how-to-build) to build the project.
-```
-
-Why: link anchors to the specific How To section, so the reader lands directly on the relevant workflow.

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.