pasika 0.1.0 → 0.1.4

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

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

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

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

package/package.json

@@ -1,16 +1,18 @@
 {
   "name": "pasika",
-  "version": "0.1.0",
-  "description": "Reusable Claude Code base config package",
+  "version": "0.1.4",
+  "description": "Reusable agent setup package",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Bredansky/pasika"
+  },
   "license": "MIT",
   "type": "module",
-  "scripts": {
-    "build": "rm -rf dist AGENTS.md CLAUDE.md && tsc -p tsconfig.json && npx vulyk docs",
-    "check": "npm run lint && npm run typecheck",
-    "fix": "eslint . --fix",
-    "lint": "eslint .",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "prepack": "npm run build"
+  "exports": {
+    "./eslint": {
+      "types": "./dist/eslint/pasika/index.d.ts",
+      "import": "./dist/eslint/pasika/index.js"
+    }
   },
   "bin": {
     "pasika": "dist/scripts/pasika.js"
@@ -23,12 +25,24 @@
     "CLAUDE.md",
     "README.md"
   ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json && tsc -p tsconfig.eslint.json",
+    "check": "npm run lint && npm run typecheck",
+    "docs:generate": "rm -f AGENTS.md CLAUDE.md && npx vulyk docs",
+    "fix": "eslint . --fix",
+    "lint": "eslint .",
+    "prepack": "npm run build",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.eslint.json --noEmit"
+  },
   "devDependencies": {
     "@types/node": "^24.12.2",
     "eslint": "^9.39.4",
     "prettier": "^3.8.1",
     "typescript": "^5.9.2",
-    "vulyk": "^0.6.1",
+    "vulyk": "github:Bredansky/vulyk#829cac4a244add961304070474db3e978db01d2a",
     "zirka": "^0.0.28"
+  },
+  "engines": {
+    "node": ">=22"
   }
 }

package/AGENTS.md

@@ -1,15 +0,0 @@
-# pasika
-pasika scope and usage.
-Full documentation: docs/common/overview.md
-
----
-
-# Merge Behavior
-How pasika merges into existing Claude settings.
-Full documentation: docs/common/merge-behavior.md
-
----
-
-# Claude Hooks
-Shared Claude hooks shipped by pasika.
-Full documentation: docs/claude/hooks.md

package/docs/common/merge-behavior.md

@@ -1,17 +0,0 @@
-# Merge Behavior
-
-`pasika` merges into an existing `.claude/settings.json` by default.
-
-It updates the Claude base pieces owned by `pasika`:
-
-- `hooks.Notification`
-- `hooks.PreToolUse`
-- `statusLine`
-
-It preserves unrelated project-specific settings such as:
-
-- custom permissions
-- extra hooks like `PostToolUse`
-- plugin and marketplace config
-
-Use `--force` only when you want to replace the file instead of merging.

package/docs/common/overview.md

@@ -1,20 +0,0 @@
-# pasika
-
-`pasika` is a reusable Claude Code base package.
-
-## Scope
-
-- Claude only for v1
-- shared hooks and base settings
-- merge-friendly project integration
-- no project-specific skills, rules, or plugin choices
-
-## Usage
-
-Install `pasika` as a dev dependency, then run:
-
-```bash
-npx pasika claude
-```
-
-That generates or updates `.claude/settings.json` to point shared hooks at `./node_modules/pasika/claude/...`.