-
Notifications
You must be signed in to change notification settings - Fork 0
Enhance documentation by adding a Developer section in SUMMARY.md and… #8
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
thomaskimura
wants to merge
1
commit into
main
Choose a base branch
from
thomas/bl-404-write-developer-docs-for-slab
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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/`. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Local machine paths committed to public documentation
Medium Severity
Every new documentation file under
slab/developer/contains "Canonical files" sections listing absolute paths rooted at/Users/thomaskimura/Documents/GitHub/slab/. These are one developer's local machine paths and are meaningless — and potentially confusing or embarrassing — to anyone else reading the published docs. The same pattern appears in all seven new files:agent-skills-and-commands.md,css.md,github-actions.md,javascript.md,project-setup.md,using-ai.md, andvariables.md. These paths were likely generated by an AI tool that captured the author's local environment and should be repository-relative paths instead.Additional Locations (2)
slab/developer/css.md#L6-L10slab/developer/github-actions.md#L6-L10