diff --git a/slab/README.md b/slab/README.md index 8887fd6..8fad6c1 100644 --- a/slab/README.md +++ b/slab/README.md @@ -2,7 +2,7 @@ ### Helpful links -
BlocksBroken link
+
BlocksBroken link
Developerdeveloper
### Theme versions diff --git a/slab/SUMMARY.md b/slab/SUMMARY.md index 829f199..bc5b1c4 100644 --- a/slab/SUMMARY.md +++ b/slab/SUMMARY.md @@ -2,6 +2,17 @@ * [Slab documentation](README.md) +## Developer + +* [Developer overview](developer/README.md) + * [Project setup](developer/project-setup.md) + * [GitHub Actions](developer/github-actions.md) + * [Using AI](developer/using-ai.md) + * [Agent skills and commands](developer/agent-skills-and-commands.md) + * [CSS](developer/css.md) + * [JavaScript](developer/javascript.md) + * [Global, collection, and product variables](developer/variables.md) + ## Blocks * [Blocks overview](blocks/README.md) diff --git a/slab/developer/README.md b/slab/developer/README.md new file mode 100644 index 0000000..0d82516 --- /dev/null +++ b/slab/developer/README.md @@ -0,0 +1,13 @@ +# Developer + +Technical guides for working on the Slab theme codebase. These pages reference the local `slab` repository so you can move from docs to implementation quickly. + +## Guides + +- [Project setup](project-setup.md) +- [GitHub Actions](github-actions.md) +- [Using AI](using-ai.md) +- [Agent skills and commands](agent-skills-and-commands.md) +- [CSS](css.md) +- [JavaScript](javascript.md) +- [Global, collection, and product variables](variables.md) diff --git a/slab/developer/agent-skills-and-commands.md b/slab/developer/agent-skills-and-commands.md new file mode 100644 index 0000000..15fed1f --- /dev/null +++ b/slab/developer/agent-skills-and-commands.md @@ -0,0 +1,53 @@ +# Agent skills and commands + +This page summarizes built-in skills and command prompts used in the Slab repository for repeatable AI workflows. + +## Canonical files + +- `/Users/thomaskimura/Documents/GitHub/slab/.agents/skills/` +- `/Users/thomaskimura/Documents/GitHub/slab/.cursor/skills/` +- `/Users/thomaskimura/Documents/GitHub/slab/.cursor/commands/` + +## Agent skills in this repo + +Under `.agents/skills/`: + +- `agent-browser`: browser-driven QA workflow +- `find-skills`: helper for skill discovery +- `skill-creator`: helper for creating/updating skills + +Under `.cursor/skills/`: + +- `update-shopify-json`: workflow for safer Shopify JSON template updates + +## Cursor command prompts + +Current command files under `.cursor/commands/` include: + +- `review-liquid.md` +- `review-javascript.md` +- `review-alpine.md` +- `review-accessibility.md` +- `review-performance.md` +- `review-submission.md` +- `prepare-submission.md` +- `fix-breaking-changes.md` +- `fix-accessibility-issue.md` +- `format-presets.md` +- `add-block-documentation.md` +- `add-doc.md` +- `add-comment.md` +- `update-translations.md` +- `update-schema-translations.md` + +## Suggested usage pattern + +- Use review commands first to identify risks. +- Use fix/format commands for scoped follow-up changes. +- Use docs/translation commands when updating schema, locales, or markdown docs. +- Keep command usage tied to changed files and target branch scope. + +## Gotchas + +- Command files are prompts, not executable scripts. Validate outcomes with theme check, local preview, and targeted QA. +- Skills can overlap in purpose; prefer the most specific skill/command for the current task. diff --git a/slab/developer/css.md b/slab/developer/css.md new file mode 100644 index 0000000..01434d6 --- /dev/null +++ b/slab/developer/css.md @@ -0,0 +1,51 @@ +# CSS + +Slab uses Tailwind CSS v4 plus custom utility layers to keep styling consistent across sections, blocks, and snippets. + +## Canonical files + +- `/Users/thomaskimura/Documents/GitHub/slab/src/entrypoints/styles.css` +- `/Users/thomaskimura/Documents/GitHub/slab/src/css/utilities/colors.css` +- `/Users/thomaskimura/Documents/GitHub/slab/src/css/base/colors.css` +- `/Users/thomaskimura/Documents/GitHub/slab/postcss.config.js` + +## CSS architecture + +- `src/entrypoints/styles.css` is the main stylesheet entrypoint. +- Tailwind is loaded with `@import 'tailwindcss';`. +- Utility, base, and component styles are imported in layers from `src/css/...`. +- `postcss.config.js` enables `@tailwindcss/postcss`. + +## Classes and naming + +- Utility and component classes follow repository naming conventions from `.cursor/rules`. +- You will see utility naming patterns like: + - `color-bg__...` for backgrounds + - `color-tx__...` for text + - `color-br__...` for borders + - `color-bt__...` for button styles +- Section and block settings often output classes directly in Liquid templates (for example color and border classes in section schema options). + +## Colors and schemes + +- Color tokens are driven by CSS variables (for example `--color__background-body`, `--scheme__background`). +- `src/css/utilities/colors.css` maps tokens to reusable utilities. +- Many schema settings expose color choices as class values, then templates apply those classes at render time. + +## Tailwind specifics + +- Tailwind v4 is configured through CSS import + PostCSS plugin (no traditional `tailwind.config.js` in current repo state). +- Dynamic class generation is handled with `@source inline(...)` safelists in `styles.css`. +- Keep dynamic class patterns synchronized with template-generated class names to avoid purge-related missing styles. + +## Recommended approach for CSS changes + +1. Prefer existing utility classes before adding new ones. +2. If adding utilities, place them in the closest matching file under `src/css/utilities/`. +3. If introducing new token usage, align with existing `--color__...` or `--scheme__...` variables. +4. Verify in both desktop and mobile views, especially for classes generated by schema settings. + +## Gotchas + +- If a class is generated dynamically from settings and not safelisted, Tailwind may not emit it. +- Color behavior often depends on class combinations (`background + text + border`), not single classes in isolation. diff --git a/slab/developer/github-actions.md b/slab/developer/github-actions.md new file mode 100644 index 0000000..89ea023 --- /dev/null +++ b/slab/developer/github-actions.md @@ -0,0 +1,60 @@ +# GitHub Actions + +Slab currently includes GitHub Actions workflows for theme checks, Lighthouse checks, PR review automation, and a paused Playwright pipeline. + +## Canonical files + +- `/Users/thomaskimura/Documents/GitHub/slab/.github/workflows/check-theme.yml` +- `/Users/thomaskimura/Documents/GitHub/slab/.github/workflows/check-lighthouse.yml` +- `/Users/thomaskimura/Documents/GitHub/slab/.github/workflows/review-rules.yml` +- `/Users/thomaskimura/Documents/GitHub/slab/.github/workflows/test-playwright.yml` + +## Active workflows + +### Theme check + +- Trigger: `push` +- Action: `shopify/theme-check-action@v2` +- Purpose: run Shopify Theme Check against repository theme files + +### Lighthouse check + +- Trigger: `push` +- Action: `shopify/lighthouse-ci-action@v1` +- Purpose: enforce Lighthouse performance/accessibility thresholds +- Uses store credentials from repository secrets + +### Review rules + +- Trigger: pull requests (`opened`, `synchronize`, `reopened`, `ready_for_review`) +- Purpose: run Cursor-based automated review using `.cursor/rules` +- Skips branches starting with `docs/` + +## Paused workflow + +### Playwright tests + +- Trigger: pull requests +- Current status: paused (`if: false`) +- Behavior when enabled: + - installs dependencies and Playwright Chromium + - deploys preview theme + - runs E2E tests + - posts PR comment with results + - cleans up preview theme + +## Required secrets + +Depending on workflow: + +- `GITHUB_TOKEN` +- `CURSOR_API_KEY` +- `SHOP_STORE` +- `SHOP_PASSWORD` +- `SHOP_ACCESS_TOKEN` +- `LHCI_GITHUB_APP_TOKEN` + +## Gotchas + +- Some repo docs still say there is no GitHub Actions CI. The workflow files above are the source of truth. +- The Playwright workflow exists but is intentionally paused, so `test:e2e` remains a local/manual path unless CI is re-enabled. diff --git a/slab/developer/javascript.md b/slab/developer/javascript.md new file mode 100644 index 0000000..f03e26c --- /dev/null +++ b/slab/developer/javascript.md @@ -0,0 +1,55 @@ +# JavaScript + +Slab JavaScript is Alpine-first: core behavior is composed into a single global app object, then consumed by `x-data` components across theme templates. + +## Canonical files + +- `/Users/thomaskimura/Documents/GitHub/slab/src/entrypoints/main.js` +- `/Users/thomaskimura/Documents/GitHub/slab/src/javascript/app.ts` +- `/Users/thomaskimura/Documents/GitHub/slab/src/javascript/core/utils.ts` +- `/Users/thomaskimura/Documents/GitHub/slab/src/javascript/core/cart.ts` +- `/Users/thomaskimura/Documents/GitHub/slab/src/javascript/core/products.ts` +- `/Users/thomaskimura/Documents/GitHub/slab/layout/theme.liquid` +- `/Users/thomaskimura/Documents/GitHub/slab/snippets/theme__scripts.liquid` + +## Runtime structure + +- `main.js` initializes Alpine, registers plugins, sets async component loading, and starts Alpine. +- `app.ts` composes core modules into `window.app()`. +- `theme.liquid` binds root HTML with `x-data="app()"` and root `x-init` lifecycle calls. +- `theme__scripts.liquid` seeds Alpine stores (`config`, `cart`, `filter`, `search`, `feedback`, `overlays`). + +## Events used across the theme + +Custom event dispatch happens through `utils.dispatchEvent(...)`, then listeners react in components and blocks. + +Common events from cart flows: + +- `cart:change` +- `cart:error` + +These are dispatched during add/update/change/note/discount operations in `core/cart.ts`. + +## Alpine component strategy + +- Async components load from `src/javascript/components/*.ts` via `AsyncAlpine`. +- Product and collection features rely on Alpine store state plus `x-data` payloads from Liquid snippets. +- Overlay interactions are centralized in `utils.ts` (`openOverlay`, `closeOverlay`, `toggleOverlay`, `closeAllOverlays`). + +## Working with product interactions + +- `core/products.ts` handles variant selection, option state, URL sync, selling plan calculations, and dynamic template fetch/injection. +- Product templates pass structured product data through `helper__product-object.liquid`. +- Keep server-rendered Liquid data and client-side TypeScript assumptions aligned when adding new fields. + +## Recommended approach for JavaScript changes + +1. Add shared behavior to `core/*` modules first. +2. Expose needed methods through `window.app()` composition in `app.ts`. +3. Keep Alpine store shape consistent with `theme__scripts.liquid`. +4. Use custom events for cross-component communication rather than tight coupling. + +## Gotchas + +- Repo docs include mixed statements about Playwright status; check actual scripts/workflows before changing testing docs. +- Store key naming can vary (`camelCase` vs `snake_case` expectations in some formatting helpers). Validate fallbacks before refactors. diff --git a/slab/developer/project-setup.md b/slab/developer/project-setup.md new file mode 100644 index 0000000..d12fd09 --- /dev/null +++ b/slab/developer/project-setup.md @@ -0,0 +1,68 @@ +# Project setup + +This guide covers the fastest way to run Slab locally and understand the core scripts used during development. + +## Canonical files + +- `/Users/thomaskimura/Documents/GitHub/slab/README.md` +- `/Users/thomaskimura/Documents/GitHub/slab/package.json` +- `/Users/thomaskimura/Documents/GitHub/slab/AGENTS.md` + +## Requirements + +- Node.js 18+ and npm +- Shopify CLI 3+ +- Access to a development Shopify store + +## Initial setup + +1. Clone Slab locally: + ```sh + git clone git@github.com:BrickspaceLab/slab.git + ``` +2. Install dependencies: + ```sh + npm install + ``` +3. Create `.env` from `.env.example`. +4. Authenticate Shopify CLI: + ```sh + shopify auth login --store your-store.myshopify.com + ``` + +## Start local development + +Run: + +```sh +npm run dev +``` + +This starts three processes in parallel: + +- `vite dev` +- `shopify theme dev --store ...` +- `node src/scripts/section-builder.js --watch` + +## Common scripts + +- `npm run dev`: full local dev loop +- `npm run build`: build sections and Vite assets +- `npm run theme-check`: Shopify Theme Check (writes to `check.md`) +- `npm run json-check`: JSON-focused Theme Check +- `npm run test:e2e`: Playwright tests + +## Environment variables + +Common local variables: + +- `SHOPIFY_CLI_THEME_TOKEN`: Theme Access app token for Shopify CLI auth +- `SHOP_PASSWORD`: storefront password for protected development stores + +If your store is password-protected, you may need to run Shopify CLI manually with `--store-password`. + +## Gotchas + +- The Vite dev URL is not the full storefront preview. Use the Shopify preview URL from `shopify theme dev`. +- Theme checks can take several minutes on larger changesets. +- Repo docs contain mixed guidance about Playwright and CI; verify current behavior from `package.json` and `.github/workflows/`. diff --git a/slab/developer/using-ai.md b/slab/developer/using-ai.md new file mode 100644 index 0000000..6485451 --- /dev/null +++ b/slab/developer/using-ai.md @@ -0,0 +1,43 @@ +# Using AI + +Slab is set up to use AI-assisted workflows for implementation, review, and documentation with project-specific rules and command prompts. + +## Canonical files + +- `/Users/thomaskimura/Documents/GitHub/slab/AGENTS.md` +- `/Users/thomaskimura/Documents/GitHub/slab/.cursor/rules/` +- `/Users/thomaskimura/Documents/GitHub/slab/.cursor/commands/` + +## How AI guidance is organized + +- `.cursor/rules/`: coding standards for Liquid, JavaScript, Alpine, CSS, naming, localization, performance, and accessibility +- `.cursor/commands/`: reusable prompts for common tasks like reviews, docs generation, formatting, and submission preparation +- `AGENTS.md`: repo-specific instructions and runtime caveats for agents + +## Recommended workflow + +1. Start from a focused command (for example `/review-liquid` or `/review-javascript`). +2. Apply fixes against changed files only. +3. Re-run a targeted review command for validation. +4. Use `/prepare-submission` before release-related handoff. + +## High-value review commands + +- `/review-liquid` +- `/review-javascript` +- `/review-alpine` +- `/review-accessibility` +- `/review-performance` +- `/review-submission` + +## Writing better prompts in this repo + +- Reference exact files and components instead of broad requests. +- Ask for rule-based checks tied to `.cursor/rules`. +- Keep scope narrow (single bug, single component, or single workflow). +- Request concrete outputs (diff-ready edits, checklist, or risk findings). + +## Gotchas + +- Rules and workflow docs evolve quickly; verify the latest behavior in `.cursor/rules`, `.cursor/commands`, and `.github/workflows`. +- Some historical docs mention local-only review flows; current repo state also includes automated review in GitHub Actions. diff --git a/slab/developer/variables.md b/slab/developer/variables.md new file mode 100644 index 0000000..3b7a5b4 --- /dev/null +++ b/slab/developer/variables.md @@ -0,0 +1,91 @@ +# Global, collection, and product variables + +Slab data flow combines Shopify Liquid objects, section/block settings, and Alpine stores. This page maps where each variable group comes from and where it is consumed. + +## Canonical files + +- `/Users/thomaskimura/Documents/GitHub/slab/layout/theme.liquid` +- `/Users/thomaskimura/Documents/GitHub/slab/snippets/theme__scripts.liquid` +- `/Users/thomaskimura/Documents/GitHub/slab/snippets/helper__product-object.liquid` +- `/Users/thomaskimura/Documents/GitHub/slab/sections/main__product.liquid` +- `/Users/thomaskimura/Documents/GitHub/slab/sections/main__collection.liquid` +- `/Users/thomaskimura/Documents/GitHub/slab/blocks/filter.liquid` +- `/Users/thomaskimura/Documents/GitHub/slab/src/javascript/core/products.ts` +- `/Users/thomaskimura/Documents/GitHub/slab/src/javascript/core/cart.ts` + +## Data flow overview + +```mermaid +flowchart TD + themeLiquid["layout/theme.liquid"] --> themeScripts["snippets/theme__scripts.liquid"] + themeScripts --> alpineStores["Alpine stores: config cart filter search overlays"] + productSection["sections/main__product.liquid"] --> productHelper["snippets/helper__product-object.liquid"] + productHelper --> productState["x-data product state"] + collectionSection["sections/main__collection.liquid"] --> filterBlock["blocks/filter.liquid"] + filterBlock --> filterState["Alpine store filter"] + alpineStores --> appRuntime["window.app() runtime methods"] + productState --> appRuntime + filterState --> appRuntime +``` + +## Global variables + +Primary source: `theme.liquid` and `theme__scripts.liquid`. + +Examples: + +- Theme settings from `settings.*` +- Request/customer/shop context (`request`, `customer`, `shop`, `routes`) +- Alpine global stores: + - `config` + - `cart` + - `filter` + - `pagination` + - `search` + - `feedback` + - `overlays` + +Use global store values when behavior is cross-page (cart UI, overlays, search, account/login state, global toggles). + +## Product variables + +Primary source: `helper__product-object.liquid` rendered into `x-data` in `main__product.liquid`. + +Key product payload fields: + +- `product` (serialized Shopify product object) +- `variants` map and selected variant IDs +- option and unavailable-option state fields (`option1`, `unavailableOption1`, etc.) +- selling plan structures and calculated pricing fields +- flags such as `isQuickEdit`, `isQuickBuy`, `enableDefaultVariant` + +Runtime logic in `core/products.ts` mutates these fields as the customer selects variants, selling plans, or quick-buy/edit flows. + +## Collection variables + +Primary source: collection/search Liquid objects in `blocks/filter.liquid` and section settings in `main__collection.liquid`. + +Common collection/search data: + +- `results` assigned from `collection` or `search` +- `results.filters` +- active filter counts +- sort state +- price range min/max derived from filter values + +These values initialize Alpine filter state and drive interactive filtering/sorting behavior. + +## Best practices + +- Keep variable ownership clear: + - Liquid for initial truth and server-rendered context + - Alpine stores for client-side interactive state +- When adding new fields, update both: + - Liquid output source (snippet/section/block) + - TypeScript/Alpine consumers +- Prefer extending existing stores and data objects over creating disconnected globals. + +## Gotchas + +- Product data shape can drift if new Liquid fields are added without TypeScript updates. +- Collection filter behavior depends on template context (`collection` vs `search`), so test both paths.