@numbered/docs-to-context 0.1.4 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # @numbered/docs-to-context
 
-Extract component APIs, design system docs, and architecture specs into structured references and inject a compact index into `CLAUDE.md` — so AI agents always know what's available without hallucinating.
+Extract component APIs, design system docs, best practices, and architecture specs into structured references and inject a compact index into `CLAUDE.md` — so AI agents always know what's available without hallucinating.
 
 ## Usage
 
@@ -12,7 +12,7 @@ Run from the project root. Auto-detects platform (Next.js or Shopify).
 
 ### Options
 
-```bash
+```
 bunx @numbered/docs-to-context [project_root] [options]
 
 --platform nextjs|shopify   Force platform detection
@@ -20,32 +20,76 @@ bunx @numbered/docs-to-context [project_root] [options]
 --output path               Custom output directory
 ```
 
+### Output
+
+```
+  @numbered/docs-to-context
+  ─────────────────────
+
+  Extract
+  ● Platform: nextjs
+  ✓ Extracted 74 components
+    /path/to/project/.context/components
+
+  Inject
+  ✓ Copied 1 best practice doc(s)
+  ● Found 15 core doc(s)
+  ✓ Injected index into CLAUDE.md
+
+  Done.
+```
+
 ## What it does
 
-1. **Extracts** component APIs from source files into per-component MDX docs at `docs/components/`
-2. **Discovers** core docs if present (design system, grid system, architecture specs)
-3. **Injects** a compact index between `<!-- PROJECT_DOCS_START -->` / `<!-- PROJECT_DOCS_END -->` markers in `CLAUDE.md`
-4. **Adds** `docs/components/` to `.gitignore`
+1. **Extracts** component APIs from source files into per-component MDX docs at `.context/components/`
+2. **Copies** platform-specific best practice docs to `.context/best-practices/`
+3. **Discovers** core docs if present (design system, grid system, architecture specs)
+4. **Injects** a compact index between `<!-- PROJECT_DOCS_START -->` / `<!-- PROJECT_DOCS_END -->` markers in `CLAUDE.md`
+5. **Adds** `.context/` to `.gitignore`
 
 ### Injected format
 
-Follows the [Vercel compressed folder path convention](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals):
+Follows the [Vercel compressed folder path convention](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals). Files are grouped by directory to minimize token usage:
 
 ```markdown
 <!-- PROJECT_DOCS_START -->
+
 ## Project Docs
+
 |[Frontend]|root: ./docs
 |frontend:{design-system.md,grid-system.md}
-[Component Index]|root: ./docs/components
+|[Best Practices]|root: ./.context
+|best-practices:{react-rules.mdx}
+|IMPORTANT: Read best practice docs before writing code
+[Component Index]|root: ./.context/components
 |IMPORTANT: Read component MDX before using any component
 |components:{Button.mdx,Carousel.mdx,Container.mdx}
-|If ./docs/components is missing, run: bunx @numbered/docs-to-context
+|If ./.context/components is missing, run: bunx @numbered/docs-to-context
 |[Entities]|root: ./docs
 |specs/architecture:{README.md,entities.md,entity-relationship-diagram.md}
 |specs/architecture/entities:{about.md,journal.md,happening.md}
+
 <!-- PROJECT_DOCS_END -->
 ```
 
+Four sections:
+
+- **Frontend** — design tokens, grid/layout (read before styling)
+- **Best Practices** — platform-specific coding rules (read before writing code)
+- **Components** — per-component MDX with props, variants, defaults
+- **Entities** — content architecture (read before schema/data work)
+
+## Best practices
+
+The package bundles best-practice docs per platform:
+
+| Platform | Folder         | Contents                                |
+| -------- | -------------- | --------------------------------------- |
+| Next.js  | `docs/react/`  | React rules (re-renders, effects, etc.) |
+| Shopify  | `docs/liquid/` | Liquid rules (performance, Alpine.js)   |
+
+These are copied to `.context/best-practices/` at generation time. More docs can be added to each folder.
+
 ## Supported platforms
 
 ### Next.js
@@ -69,17 +113,28 @@ Scans `snippets/*.liquid` and extracts:
 
 The following files are automatically included in the index when present:
 
-| Section | Path | Purpose |
-|---|---|---|
-| Frontend | `docs/design-system.md` | Design tokens, typography, colors |
-| Frontend | `docs/grid-system.md` | Grid system, breakpoints, fluid utilities |
+| Section  | Path                              | Purpose                                   |
+| -------- | --------------------------------- | ----------------------------------------- |
+| Frontend | `docs/design-system.md`           | Design tokens, typography, colors         |
+| Frontend | `docs/grid-system.md`             | Grid system, breakpoints, fluid utilities |
 | Entities | `docs/specs/architecture/**/*.md` | Document types, ER diagrams, entity specs |
 
+## Fresh clone
+
+Since `.context/` is gitignored, agents on a fresh clone will see:
+
+```
+|If ./.context/components is missing, run: bunx @numbered/docs-to-context
+```
+
+No plugin install, no auth — just `bun` and the public npm package.
+
 ## Publishing
 
 ```bash
-cd packages/project-docs
+cd packages/docs-to-context
 npm login --scope=@numbered
-bun run publish:dry     # preview
-bun run publish:npm     # publish to npm (public)
+bun run publish:dry       # preview
+bun run publish:patch     # bump patch + publish
+bun run publish:minor     # bump minor + publish
 ```

package/docs/liquid/README.mdx

@@ -0,0 +1,59 @@
+# Liquid & Shopify Best Practices
+
+Read this index first. Load only the files relevant to your current task.
+
+## 1. Liquid Performance — CRITICAL
+
+| File | Pattern |
+|---|---|
+| `liquid-filter-early.mdx` | Filter and assign before loops |
+| `liquid-cache-assigns.mdx` | Assign once, reuse — avoid repeated filters |
+| `liquid-limit-loops.mdx` | Always use limit: on for loops |
+| `liquid-avoid-nested-loops.mdx` | Flatten nested loops with Liquid filters |
+| `liquid-break-continue.mdx` | break/continue for early loop exit |
+| `liquid-map-join.mdx` | map + join instead of string concatenation |
+| `liquid-whitespace-control.mdx` | Strip whitespace with {%- -%} tags |
+| `liquid-render-over-include.mdx` | render is faster and safer than include |
+| `liquid-snippet-data.mdx` | Pass only needed values to snippets |
+| `liquid-elsif-chain.mdx` | elsif chain over multiple if blocks |
+| `liquid-assign-over-capture.mdx` | assign over capture for simple values |
+
+## 2. Asset Loading — HIGH
+
+| File | Pattern |
+|---|---|
+| `loading-defer-scripts.mdx` | defer/async on non-critical scripts |
+| `loading-lazy-images.mdx` | Native lazy loading for below-fold images |
+| `loading-preload-critical.mdx` | Preload hero images and fonts |
+| `loading-responsive-images.mdx` | srcset for per-viewport image sizes |
+
+## 3. CSS & Styling — MEDIUM
+
+| File | Pattern |
+|---|---|
+| `css-prefer-tailwind.mdx` | Tailwind utilities over CSS variables |
+| `css-critical-inline.mdx` | Inline critical CSS, async load the rest |
+
+## 4. Alpine.js Performance — MEDIUM
+
+| File | Pattern |
+|---|---|
+| `alpine-debounce.mdx` | Debounce expensive watchers/handlers |
+| `alpine-static-data.mdx` | Move static data outside reactive scope |
+| `alpine-defer-heavy.mdx` | Defer heavy content with $nextTick |
+| `alpine-separate-scopes.mdx` | Split x-data into separate concerns |
+| `alpine-cleanup.mdx` | Clean up listeners in destroy() |
+
+## 5. Schema Design — MEDIUM
+
+| File | Pattern |
+|---|---|
+| `schema-section-settings.mdx` | Lean settings, map to Tailwind in template |
+| `schema-blocks-over-settings.mdx` | Blocks for repeatable content, not numbered settings |
+
+## 6. Accessibility — MEDIUM
+
+| File | Pattern |
+|---|---|
+| `a11y-semantic-html.mdx` | Semantic elements over div+role |
+| `a11y-alt-text.mdx` | Alt text on all images, escaped |

package/docs/liquid/a11y-alt-text.mdx

@@ -0,0 +1,16 @@
+# Always Provide Alt Text
+
+Every `<img>` must have an `alt` attribute. Use the Shopify image alt field, with a fallback.
+
+```liquid
+{% comment %} BAD: no alt text {% endcomment %}
+<img src="{{ image | image_url: width: 800 }}">
+
+{% comment %} GOOD: alt from image object {% endcomment %}
+<img src="{{ image | image_url: width: 800 }}" alt="{{ image.alt | escape }}">
+
+{% comment %} For decorative images {% endcomment %}
+<img src="{{ image | image_url: width: 800 }}" alt="" role="presentation">
+```
+
+Escape alt text to prevent XSS via CMS-injected content.

package/docs/liquid/a11y-semantic-html.mdx

@@ -0,0 +1,19 @@
+# Use Semantic HTML
+
+Use proper HTML elements instead of generic divs with ARIA roles.
+
+```liquid
+{% comment %} BAD {% endcomment %}
+<div class="nav" role="navigation">
+  <div class="nav-item" onclick="...">Home</div>
+</div>
+
+{% comment %} GOOD {% endcomment %}
+<nav>
+  <a href="/">Home</a>
+</nav>
+```
+
+Key elements: `<nav>`, `<main>`, `<header>`, `<footer>`, `<article>`, `<section>`, `<button>`, `<a>`.
+
+Only use `<div>` for layout wrappers with no semantic meaning.

package/docs/liquid/alpine-cleanup.mdx

@@ -0,0 +1,18 @@
+# Clean Up Alpine.js Event Listeners
+
+Always clean up manual event listeners and intervals in `destroy()` to prevent memory leaks on section re-render.
+
+```typescript
+component: () => ({
+  resizeHandler: null,
+  init() {
+    this.resizeHandler = () => this.onResize()
+    window.addEventListener('resize', this.resizeHandler)
+  },
+  destroy() {
+    window.removeEventListener('resize', this.resizeHandler)
+  }
+})
+```
+
+Alpine calls `destroy()` when the element is removed from the DOM (e.g. section reorder in the editor).

package/docs/liquid/alpine-debounce.mdx

@@ -0,0 +1,12 @@
+# Debounce Expensive Alpine.js Operations
+
+Wrap watchers and event handlers with debounce to avoid firing on every keystroke/scroll.
+
+```typescript
+component: () => ({
+  search: '',
+  init() {
+    this.$watch('search', debounce((value) => this.performSearch(value), 300))
+  }
+})
+```

package/docs/liquid/alpine-defer-heavy.mdx

@@ -0,0 +1,13 @@
+# Defer Heavy Alpine.js Components
+
+Delay rendering of heavy content until after initial load using `$nextTick`.
+
+```html
+<div x-data="{ loaded: false }" x-init="$nextTick(() => loaded = true)">
+  <template x-if="loaded">
+    <!-- Heavy content rendered after initial load -->
+  </template>
+</div>
+```
+
+Useful for carousels, maps, complex forms, and anything below the fold.

package/docs/liquid/alpine-separate-scopes.mdx

@@ -0,0 +1,19 @@
+# Separate Alpine.js x-data Scopes
+
+Avoid monolithic reactive objects. Split concerns into nested `x-data` scopes.
+
+```html
+<!-- BAD: large reactive object -->
+<div x-data="{ items: [...], filters: {...}, sort: {...}, pagination: {...} }">
+
+<!-- GOOD: separate concerns -->
+<div x-data="productFilters">
+  <div x-data="productSort">
+    <div x-data="productPagination">
+      ...
+    </div>
+  </div>
+</div>
+```
+
+Each scope only re-evaluates when its own data changes.

package/docs/liquid/alpine-static-data.mdx

@@ -0,0 +1,16 @@
+# Minimize Alpine.js Reactive Data
+
+Static data inside `x-data` becomes reactive — Alpine tracks changes to it even though it never changes. Move static data outside.
+
+```typescript
+// BAD: static data as reactive
+component: () => ({
+  options: ['Option 1', 'Option 2', 'Option 3'],
+})
+
+// GOOD: static data outside component
+const OPTIONS = ['Option 1', 'Option 2', 'Option 3']
+component: () => ({
+  selectedOption: OPTIONS[0],
+})
+```

package/docs/liquid/css-critical-inline.mdx

@@ -0,0 +1,16 @@
+# Inline Critical CSS
+
+Inline above-the-fold styles to avoid render-blocking stylesheet requests.
+
+```liquid
+{% comment %} BAD: external stylesheet blocks first paint {% endcomment %}
+{{ 'section-hero.css' | asset_url | stylesheet_tag }}
+
+{% comment %} GOOD: inline critical styles for first paint {% endcomment %}
+<style>
+  .hero { min-height: 60vh; display: flex; align-items: center; }
+</style>
+
+{% comment %} Load non-critical CSS async {% endcomment %}
+<link rel="stylesheet" href="{{ 'section-hero.css' | asset_url }}" media="print" onload="this.media='all'">
+```

package/docs/liquid/css-prefer-tailwind.mdx

@@ -0,0 +1,30 @@
+# Prefer Tailwind Over Custom CSS Variables
+
+Use Tailwind utilities instead of custom CSS variables.
+
+```liquid
+{% comment %} BAD {% endcomment %}
+<style>--card-padding: 1rem;</style>
+<div class="card">
+
+{% comment %} GOOD {% endcomment %}
+<div class="p-16">
+```
+
+Only use CSS variables for:
+
+- Dynamic values from CMS settings
+- Theme-wide color schemes
+- Complex calculations not expressible with utilities
+
+When necessary, scope to section ID:
+
+```liquid
+{%- if section.settings.background_color != blank -%}
+  <style>
+    #section-{{ section.id }} {
+      --section-bg: {{ section.settings.background_color }};
+    }
+  </style>
+{%- endif -%}
+```

package/docs/liquid/liquid-assign-over-capture.mdx

@@ -0,0 +1,17 @@
+# Prefer assign Over capture
+
+`assign` is lighter weight than `capture` for simple values. Reserve `capture` for multi-line HTML blocks.
+
+```liquid
+{% comment %} BAD: capture for a simple value {% endcomment %}
+{% capture product_class %}product-card{% endcapture %}
+
+{% comment %} GOOD: assign for simple values {% endcomment %}
+{% assign product_class = 'product-card' %}
+
+{% comment %} OK: capture for multi-line HTML {% endcomment %}
+{% capture card_content %}
+  <h3>{{ product.title }}</h3>
+  <p>{{ product.price | money }}</p>
+{% endcapture %}
+```

package/docs/liquid/liquid-avoid-nested-loops.mdx

@@ -0,0 +1,21 @@
+# Avoid Nested Loops
+
+Nested `for` loops multiply iterations. Flatten with assigns or use Liquid filters.
+
+```liquid
+{% comment %} BAD: O(n*m) — 50 products x 10 tags = 500 iterations {% endcomment %}
+{% for product in collection.products %}
+  {% for tag in product.tags %}
+    {% if tag == 'sale' %}
+      ...
+    {% endif %}
+  {% endfor %}
+{% endfor %}
+
+{% comment %} GOOD: filter directly {% endcomment %}
+{% for product in collection.products %}
+  {% if product.tags contains 'sale' %}
+    ...
+  {% endif %}
+{% endfor %}
+```

package/docs/liquid/liquid-break-continue.mdx

@@ -0,0 +1,23 @@
+# Use break and continue in Loops
+
+Stop processing once target data is found, or skip irrelevant iterations.
+
+```liquid
+{% comment %} GOOD: stop after finding first match {% endcomment %}
+{% for product in collection.products %}
+  {% if product.tags contains 'featured' %}
+    {% assign featured_product = product %}
+    {% break %}
+  {% endif %}
+{% endfor %}
+
+{% comment %} GOOD: skip unavailable items {% endcomment %}
+{% for product in collection.products %}
+  {% unless product.available %}
+    {% continue %}
+  {% endunless %}
+  <div class="product-card">{{ product.title }}</div>
+{% endfor %}
+```
+
+`break` avoids iterating the entire collection when you only need one result. `continue` skips rendering for items that don't qualify.

package/docs/liquid/liquid-cache-assigns.mdx

@@ -0,0 +1,16 @@
+# Cache Expensive Assigns
+
+Assign filtered/transformed values once, then reuse. Avoid repeating Liquid filters on the same data.
+
+```liquid
+{% comment %} BAD: escape runs twice {% endcomment %}
+<a href="{{ product.url | within: collection }}">{{ product.title | escape }}</a>
+<span>{{ product.title | escape }}</span>
+
+{% comment %} GOOD: assign once, reuse {% endcomment %}
+{% assign product_title = product.title | escape %}
+{% assign product_url = product.url | within: collection %}
+
+<a href="{{ product_url }}">{{ product_title }}</a>
+<span>{{ product_title }}</span>
+```

package/docs/liquid/liquid-elsif-chain.mdx

@@ -0,0 +1,25 @@
+# Use elsif Instead of Multiple if Blocks
+
+Mutually exclusive conditions should use `elsif` to short-circuit evaluation. Order by most likely condition first.
+
+```liquid
+{% comment %} BAD: evaluates all conditions {% endcomment %}
+{% if product.price < 25 %}
+  <span>Budget</span>
+{% endif %}
+{% if product.price >= 25 and product.price < 100 %}
+  <span>Standard</span>
+{% endif %}
+{% if product.price >= 100 %}
+  <span>Premium</span>
+{% endif %}
+
+{% comment %} GOOD: stops at first match {% endcomment %}
+{% if product.price < 25 %}
+  <span>Budget</span>
+{% elsif product.price < 100 %}
+  <span>Standard</span>
+{% else %}
+  <span>Premium</span>
+{% endif %}
+```

package/docs/liquid/liquid-filter-early.mdx

@@ -0,0 +1,18 @@
+# Filter Early, Assign Once
+
+Avoid complex logic inside loops. Filter and assign before iterating.
+
+```liquid
+{% comment %} BAD: complex logic in every iteration {% endcomment %}
+{% for product in collection.products %}
+  {% if product.available and product.price > 0 and product.tags contains 'featured' %}
+    ...
+  {% endif %}
+{% endfor %}
+
+{% comment %} GOOD: filter early, iterate lean {% endcomment %}
+{% assign featured = collection.products | where: 'available', true %}
+{% for product in featured limit: 8 %}
+  ...
+{% endfor %}
+```

package/docs/liquid/liquid-limit-loops.mdx

@@ -0,0 +1,17 @@
+# Limit Loops
+
+Always use `limit:` when you don't need all items. Unbounded loops are the #1 Liquid performance issue.
+
+```liquid
+{% comment %} BAD: iterates entire collection {% endcomment %}
+{% for product in collection.products %}
+  ...
+{% endfor %}
+
+{% comment %} GOOD: only what you need {% endcomment %}
+{% for product in collection.products limit: 8 %}
+  ...
+{% endfor %}
+```
+
+Also applies to `for` over arrays, recommendations, and search results.

package/docs/liquid/liquid-map-join.mdx

@@ -0,0 +1,16 @@
+# Use map + join Instead of String Concatenation
+
+Appending strings in a loop creates many intermediate strings. Use `map` and `join` filters instead.
+
+```liquid
+{% comment %} BAD: string concatenation in loop {% endcomment %}
+{% assign ids = '' %}
+{% for product in collection.products %}
+  {% assign ids = ids | append: product.id | append: ',' %}
+{% endfor %}
+
+{% comment %} GOOD: map + join — one operation {% endcomment %}
+{% assign ids = collection.products | map: 'id' | join: ',' %}
+```
+
+Also works for building class lists, data attributes, and comma-separated values.

package/docs/liquid/liquid-render-over-include.mdx

@@ -0,0 +1,13 @@
+# Use render Instead of include
+
+`{% render %}` is faster and safer than `{% include %}`. It creates an isolated scope (no variable leaking) and is parallelizable by Shopify's renderer.
+
+```liquid
+{% comment %} BAD: include leaks variables, slower {% endcomment %}
+{% include 'product-card' %}
+
+{% comment %} GOOD: render is isolated and faster {% endcomment %}
+{% render 'product-card', product: product, show_price: true %}
+```
+
+Always pass variables explicitly with `render`. The snippet cannot access outer scope.

package/docs/liquid/liquid-snippet-data.mdx

@@ -0,0 +1,17 @@
+# Pass Only Needed Data to Snippets
+
+Send specific values rather than entire objects when rendering snippets. Reduces serialization overhead.
+
+```liquid
+{% comment %} BAD: passes entire product object {% endcomment %}
+{% render 'product-price', product: product %}
+
+{% comment %} GOOD: passes only the values the snippet uses {% endcomment %}
+{% render 'product-price',
+  price: product.price,
+  compare_price: product.compare_at_price,
+  currency: cart.currency.iso_code
+%}
+```
+
+This also makes snippets more reusable — they depend on values, not specific object shapes.

package/docs/liquid/liquid-whitespace-control.mdx

@@ -0,0 +1,17 @@
+# Use Whitespace Control Tags
+
+Strip unnecessary whitespace from Liquid output to reduce HTML payload.
+
+```liquid
+{% comment %} BAD: extra whitespace in output {% endcomment %}
+{% if section.settings.title != blank %}
+  <h2>{{ section.settings.title }}</h2>
+{% endif %}
+
+{% comment %} GOOD: stripped output {% endcomment %}
+{%- if section.settings.title != blank -%}
+  <h2>{{ section.settings.title }}</h2>
+{%- endif -%}
+```
+
+Use `{%-` and `-%}` on control flow tags. Keep `{{` output tags without stripping when the surrounding whitespace is meaningful for layout.

package/docs/liquid/loading-defer-scripts.mdx

@@ -0,0 +1,13 @@
+# Defer Non-Critical Scripts
+
+Use `defer` and `async` attributes to prevent scripts from blocking rendering.
+
+```liquid
+{% comment %} Defer for scripts that need DOM ready {% endcomment %}
+<script src="{{ 'analytics.js' | asset_url }}" defer></script>
+
+{% comment %} Async for independent scripts {% endcomment %}
+<script src="{{ 'widget.js' | asset_url }}" async></script>
+```
+
+Never use bare `<script>` tags without `defer` or `async` unless the script must block (e.g. critical polyfills).

package/docs/liquid/loading-lazy-images.mdx

@@ -0,0 +1,31 @@
+# Lazy Load Images
+
+Use native `loading="lazy"` for below-the-fold images. Never lazy-load above-the-fold (hero) images.
+
+```liquid
+{% comment %} BAD: all images load eagerly {% endcomment %}
+<img src="{{ image | image_url: width: 800 }}" alt="{{ image.alt }}">
+
+{% comment %} GOOD: lazy load below-fold images {% endcomment %}
+<img
+  src="{{ image | image_url: width: 800 }}"
+  alt="{{ image.alt }}"
+  loading="lazy"
+  width="{{ image.width }}"
+  height="{{ image.height }}"
+>
+```
+
+Always include `width` and `height` to prevent layout shift (CLS).
+
+For hero images, use `fetchpriority="high"` instead:
+
+```liquid
+<img
+  src="{{ image | image_url: width: 1200 }}"
+  alt="{{ image.alt }}"
+  fetchpriority="high"
+  width="{{ image.width }}"
+  height="{{ image.height }}"
+>
+```

package/docs/liquid/loading-preload-critical.mdx

@@ -0,0 +1,24 @@
+# Preload Critical Assets
+
+Preload fonts, hero images, and critical CSS to improve LCP.
+
+```liquid
+{% comment %} Preload hero image {% endcomment %}
+<link
+  rel="preload"
+  as="image"
+  href="{{ section.settings.hero_image | image_url: width: 1200 }}"
+  fetchpriority="high"
+>
+
+{% comment %} Preload critical font {% endcomment %}
+<link
+  rel="preload"
+  as="font"
+  type="font/woff2"
+  href="{{ 'custom-font.woff2' | asset_url }}"
+  crossorigin
+>
+```
+
+Only preload 2-3 assets max — over-preloading has diminishing returns.