Skip to content

CLAUDE.md

Latest commit

 

History

History
209 lines (153 loc) · 11.6 KB

CLAUDE.md

File metadata and controls

209 lines (153 loc) · 11.6 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Site purpose

This is the unified documentation and marketing site for the entire @libar-dev/ ecosystem — a suite of TypeScript packages for context engineering, AI-assisted codebases, and Convex/Zod infrastructure. The site is designed to grow as packages are published; delivery-process is the first package with docs here.

Known packages to add docs for (not yet integrated):

  • @libar-dev/zod-convex-* (7 packages: zod-convex-core, zod-convex-ids, zod-convex-tables, zod-convex-codecs, zod-convex-gen, zod-convex-builders, eslint-plugin-zod-convex) — Zod-to-Convex bridge with build-time code generation. Source: github.com/libar-dev/zod-convex-packages
  • libar-platform — Source: github.com/libar-dev/libar-platform

Landing page status: Currently only a minimal Hero section is live. The original design prototype (at ../delivery-process/_designs/unified/index.html locally, Swiss Constructivist) included additional sections still to be ported: Pipeline, Capabilities, Comparison, and QuickStart. The design tokens and visual language are already implemented in src/styles/tokens.css.

Commands

pnpm dev          # sync content then start Astro dev server (localhost:4321/)
pnpm build        # sync content (prebuild) then build for production
pnpm preview      # preview production build
pnpm sync         # run content sync only (scripts/sync-content.mjs)
node scripts/sync-content.mjs --verbose  # sync with per-file logging

Package manager: pnpm. There are no tests; this is a documentation site.

Architecture

This is a three-layer content site built on Astro 5.6 + Starlight 0.37:

Layer 1 — Hand-crafted (committed to git)

  • src/pages/index.astro — Landing page (outside Starlight, uses custom layout/components)
  • src/content/docs/delivery-process/index.mdx — Package overview
  • src/content/docs/delivery-process/getting-started.md — Quick start

Layer 2 — Synced at build time (git-ignored, reproducible)

Everything under src/content/docs/delivery-process/ except the files above is generated by scripts/sync-content.mjs. The script:

  • Copies markdown from ../delivery-process/ (sibling repo) and ../delivery-process-tutorials/ for the tutorial
  • Strips H1 headings, injects Starlight frontmatter (title, sidebar order, editUrl)
  • Rewrites relative inter-doc links to absolute site paths
  • Splits a single tutorial article into numbered part files

Local dev expects sibling repos at ../delivery-process/ and ../delivery-process-tutorials/. CI uses node_modules/@libar-dev/delivery-process/ for docs content (installed from npm) and checks out libar-dev/delivery-process-tutorials for the tutorial.

Layer 3 — Build artifacts (git-ignored)

Pagefind search index, rendered Mermaid SVGs, dist/.

Key configuration files

  • astro.config.mjs — site: 'https://libar.dev' (custom domain, no base); mermaid() integration must be listed before starlight() or diagram fences won't process; sidebar groups map 1:1 to subdirectories under src/content/docs/delivery-process/
  • src/styles/tokens.css — Design tokens using --dp-* prefix (Swiss Constructivist, accent #e8530e); mapped to --sl-* in starlight-overrides.css
  • src/styles/landing.css — Styles for the custom landing page only
  • src/content.config.ts — Starlight content collection config

Extending to new packages

To add a new package's docs (e.g. zod-convex-packages):

  1. Add a source entry in scripts/sync-content.mjs SOURCES object
  2. Add sync function(s) mirroring the existing pattern
  3. Add a new src/content/docs/<package-name>/ directory with at minimum an index.mdx
  4. Add a sidebar group in astro.config.mjs
  5. Add the repo checkout to .github/workflows/deploy.yml

Deployment

GitHub Actions (.github/workflows/deploy.yml) deploys to GitHub Pages on push to main. It checks out libar-dev/delivery-process-tutorials as a sibling for the tutorial, then runs pnpm build (which triggers prebuild → sync → Astro build). Docs content (docs/, docs-live/) comes from @libar-dev/delivery-process via node_modules (installed by pnpm install).

Live at https://libar.dev — custom domain is configured; public/CNAME and site in astro.config.mjs are set.

Theme system

The landing page and Starlight docs share a single theme. Theme toggle on the landing page writes to localStorage('starlight-theme') so Starlight picks it up. The data-theme attribute on <html> drives both --dp-* token overrides and Starlight's built-in dark mode.

Reference Skill

The pencil-design skill at /Users/darkomijic/.agents/skills/pencil-design provides the rules and workflows for working with .pen files. Each session should load this skill before starting work.

Key references within the skill:

  • SKILL.md — 6 critical rules (reuse components, use variables, prevent overflow, visual verification, reuse assets, load frontend-design)
  • references/variables-and-tokens.md — Variable binding workflow and Tailwind mapping (critical for Phases 1-2)
  • references/design-system-components.md — Component reuse patterns (critical for Phases 3-4)
  • references/layout-and-text-overflow.md — Overflow prevention and snapshot_layout usage
  • references/visual-verification.md — Screenshot verification workflow (used in every phase)
  • references/asset-reuse.md — Asset copying rules
  • references/design-to-code-workflow.md — Code generation guide (relevant for Phase 5)
  • references/tailwind-shadcn-mapping.md — Tailwind/shadcn mapping tables
  • references/responsive-breakpoints.md — Responsive patterns

Pencil Design

Design File

design/libar-dev-design.pen   ← single source of design truth

Open with open_document("/Users/darkomijic/dev-projects/libar-dev-website/design/libar-dev-design.pen") if not already active.

This Project's Design System

Property Value
Aesthetic Swiss Constructivist — functional, typographic, precise
Display font Bebas Neue
Body font Outfit
Code font JetBrains Mono
Accent color #e8530e (warm orange)
CSS token prefix --dp-* (defined in src/styles/tokens.css)

Token mapping rule: Pencil variable names must correspond to --dp-* CSS custom properties for code generation to be accurate. When generating code, emit var(--dp-*) — not hardcoded hex values and not var(--sl-*) (those are Starlight internals).

Session Start Checklist

Run these before any design work:

  1. get_editor_state(include_schema: true) — live .pen schema + active selection context
  2. batch_get(filePath, patterns: [{reusable: true}]) — discover ALL existing components before inserting anything
  3. get_variables(filePath) — read current --dp-* token values
  4. get_guidelines(topic) — load relevant design rules (landing-page, design-system, code, or tailwind)
  5. get_style_guide_tags() → get_style_guide(tags) — only for new screens or major redesigns

Token → CSS → Tailwind Pipeline

Layer Rule
Pencil Use $variableName references — never hardcode #e8530e, 6, etc.
Before styling Run search_all_unique_properties to audit for hardcoded values
Bulk migration Use replace_all_matching_properties to swap hardcoded → variable refs
Generated CSS Emit var(--dp-*) custom properties
Generated Tailwind Use semantic classes (bg-primary, text-foreground) — never bg-[#e8530e] or text-[var(--dp-accent)]

Landing Page Section Status

Section Status Component File
Hero Live src/components/landing/Hero.astro
Pipeline Pending src/components/landing/delivery-process/Pipeline.astro
Capabilities / Pillars Pending src/components/landing/delivery-process/Pillars.astro
Metrics Pending src/components/landing/delivery-process/Metrics.astro
Code Examples Pending src/components/landing/delivery-process/CodeExamples.astro
Data API Pending src/components/landing/delivery-process/DataAPI.astro
MCP Callout Pending src/components/landing/delivery-process/McpCallout.astro
Workflows Pending src/components/landing/delivery-process/Workflows.astro
Comparison Pending (no file yet)
QuickStart Pending (no file yet)
Footer CTA Pending src/components/landing/delivery-process/FooterCta.astro

The original design prototype with all sections is at ../delivery-process/_designs/unified/index.html (local) — reference it for layout intent.

Operation Mini-Language Quick Reference

batch_design uses a DSL string. Key rules:

Operation Syntax Critical Rule
Insert binding=I(parent, {type, ...props}) Always assign a binding name
Update U("nodeId", {...props}) Cannot change id, type, or ref
Copy binding=C("nodeId", parent, {descendants: {...}}) Use descendants for nested overrides — NOT separate U() calls on the copy
Replace binding=R("nodeId", {...}) Replaces node entirely
Delete D("nodeId") Literal node ID only — not a binding
Move M("nodeId", parent, index?) Literal node ID only
Image G(nodeIdOrBinding, "ai"|"stock", prompt) No "image" node type — images are fills on frames/rectangles

Hard limits:

  • Max 25 ops per batch_design call — split larger work into logical sections
  • Binding names are local to one call — never reuse across calls
  • All operations in a call roll back on error — design atomically

Most Impactful Tools for This Project

Tool When to Use
get_editor_state(include_schema: true) First call in any session
batch_get(reusable: true) Before inserting any element — check if component exists
search_all_unique_properties Audit hardcoded colors/spacing before token migration
replace_all_matching_properties Bulk swap hardcoded values → variable references
snapshot_layout(problemsOnly: true) After every section — catch overflow/clipping immediately
get_screenshot Visual verification after every section
set_variables Merges by default (safe); pass replace: true only when rebuilding tokens entirely

Common Mistakes (Project-Specific)

Mistake Correct
Hardcoding #e8530e Use Pencil variable reference ($accent or equivalent)
Using Inter or system font Use Bebas Neue (display), Outfit (body), JetBrains Mono (code)
U() on descendant of a just-C()-ed node Put overrides in descendants map inside the C() call itself
Building full section then checking Screenshot + snapshot_layout(problemsOnly: true) after each section
Generating rounded-[6px] in code Use semantic Tailwind class (rounded-md)
Generating var(--dp-accent) in className Use semantic class (text-accent, bg-accent)
open_document("new") when file already exists Check get_editor_state first — file may already be open

MCPorter Typed Client (Optional Scripted Work)

If calling Pencil tools from TypeScript scripts (not interactive sessions):

npx mcporter list pencil --schema                                    # full typed signatures
npx mcporter emit-ts pencil --mode client --out scripts/pencil-client.ts  # generate typed proxy

The typed proxy (createServerProxy) auto-batches, validates arguments, and provides camelCase method names — significantly more ergonomic than raw MCP SDK for scripted design generation.