From 379967856f7699719fc0abc46be41ece6254e7f3 Mon Sep 17 00:00:00 2001 From: Devin Michael Date: Fri, 19 Jun 2026 17:06:14 +0700 Subject: [PATCH 1/5] docs: improve Spark developer onboarding --- .github/ISSUE_TEMPLATE/bug_report.yml | 67 ++++++++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 5 ++ .github/ISSUE_TEMPLATE/dx_feedback.yml | 49 +++++++++++++ .github/workflows/ci.yml | 32 +++++++++ CHANGELOG.md | 26 +++++++ CONTRIBUTING.md | 60 ++++++++++++++++ PLAN.md | 2 +- README.md | 27 ++++++- docs/README.md | 1 + docs/extending-spark.md | 97 ++++++++++++++++++++++++++ 10 files changed, 362 insertions(+), 4 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/dx_feedback.yml create mode 100644 .github/workflows/ci.yml create mode 100644 CHANGELOG.md create mode 100644 CONTRIBUTING.md create mode 100644 docs/extending-spark.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..d951b02 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,67 @@ +name: Bug report +description: Report a reproducible Spark theme issue. +title: "[Bug]: " +labels: + - bug +body: + - type: markdown + attributes: + value: | + Thanks for reporting a Spark issue. Do not include API keys, customer data, merchant credentials, or exploit details. + - type: input + id: version + attributes: + label: Spark version or commit + description: Use the README version, Git tag, or commit SHA. + placeholder: "1.1.1 or add24e9" + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected behavior + description: What should have happened? + validations: + required: true + - type: textarea + id: actual + attributes: + label: Actual behavior + description: What happened instead? + validations: + required: true + - type: textarea + id: reproduce + attributes: + label: Steps to reproduce + description: Include the smallest safe reproduction you can share. + placeholder: | + 1. Clone Spark at ... + 2. Configure ... + 3. Run ... + 4. See ... + validations: + required: true + - type: dropdown + id: surface + attributes: + label: Affected surface + options: + - Theme Settings + - Homepage section partial + - Product detail page + - Cart or side cart + - App hook + - CSS build or compatibility + - Documentation + - Other + validations: + required: true + - type: textarea + id: checks + attributes: + label: Verification + description: Paste relevant local command output. + placeholder: | + python3 -m unittest discover -s tests + python3 scripts/sass-compat.py --check assets/main.css diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..1441621 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: false +contact_links: + - name: Security reports + url: https://github.com/NextCommerceCo/spark/security/advisories/new + about: Report vulnerabilities privately. Do not open public issues with exploit details or secrets. diff --git a/.github/ISSUE_TEMPLATE/dx_feedback.yml b/.github/ISSUE_TEMPLATE/dx_feedback.yml new file mode 100644 index 0000000..9923402 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/dx_feedback.yml @@ -0,0 +1,49 @@ +name: Developer experience feedback +description: Share friction from installing, extending, debugging, or contributing to Spark. +title: "[DX]: " +labels: + - dx +body: + - type: markdown + attributes: + value: | + Use this for onboarding friction, unclear docs, confusing errors, missing examples, or extension pain. Do not include secrets or merchant-specific private data. + - type: dropdown + id: journey_stage + attributes: + label: Journey stage + options: + - Discover + - Install + - Local verification + - Store install + - Extending the theme + - Debugging + - Upgrade or release + - Contributing + validations: + required: true + - type: textarea + id: attempted + attributes: + label: What were you trying to do? + description: Describe your goal and the docs, commands, or files you used. + validations: + required: true + - type: textarea + id: friction + attributes: + label: Where did you lose time? + description: Include confusing copy, missing next steps, unclear errors, or decisions the docs forced you to guess. + validations: + required: true + - type: textarea + id: better + attributes: + label: What would have helped? + description: A command, example, screenshot, doc page, warning, or default behavior. + - type: input + id: time_lost + attributes: + label: Time lost + placeholder: "About 10 minutes" diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..69579a6 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,32 @@ +name: CI + +on: + pull_request: + push: + branches: + - main + +jobs: + verify: + name: Verify theme tooling + runs-on: ubuntu-latest + + steps: + - name: Check out repository + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.11" + + - name: Set up Node + uses: actions/setup-node@v4 + with: + node-version: "22" + + - name: Run tests + run: python3 -m unittest discover -s tests + + - name: Check committed CSS compatibility + run: python3 scripts/sass-compat.py --check assets/main.css diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..98f26c2 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,26 @@ +# Changelog + +All notable public Spark changes should be recorded here. + +Spark follows human-readable release notes rather than a strict package-manager version contract. The current public version is shown in [README.md](README.md). When releasing a new version, update the README version, add a dated changelog section, and publish a Git tag or GitHub release when the repo is ready for external consumers to pin versions. + +## Unreleased + +- Clarified the first-run path for local inspection versus installing Spark on a real Next Commerce store. +- Added contribution guidance, issue templates, CI checks, and an extension guide for theme developers. + +## 1.1.1 - 2026-06-17 + +- Added metadata-driven membership pricing presentation for product cards, PDP surfaces, and sticky add-to-cart pricing. +- Refreshed public-facing docs around components, app hooks, and public readiness. + +## 1.1.0 - 2026-04-28 + +- Expanded homepage section partials and Theme Settings coverage. +- Documented the Figma section library path, performance load order, cart events, PDP variant state, and theme settings partials. +- Committed compiled `assets/main.css` so Spark can be installed without a local Tailwind build. + +## 1.0.0 - 2026-03-20 + +- Initial public Spark starter theme for Next Commerce. +- Introduced Tailwind CSS v4, vanilla JavaScript, Web Components, committed storefront templates, and zero jQuery or Bootstrap dependency. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..4d3fdfc --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,60 @@ +# Contributing To Spark + +Spark is a public starter theme for Next Commerce storefronts. Contributions should keep the theme easy to inspect, install, customize, and safely extend. + +## Before You Start + +- Read [README.md](README.md) for the current setup and verification commands. +- Read [DESIGN.md](DESIGN.md) before changing storefront UI. +- Read [docs/extending-spark.md](docs/extending-spark.md) before adding settings, partials, app hooks, or Web Components. +- Keep `config.yml`, API keys, store domains, merchant data, and local tool state out of commits. + +## Local Verification + +Run the checks that match your change: + +```bash +python3 -m unittest discover -s tests +python3 scripts/sass-compat.py --check assets/main.css +``` + +If you change `css/input.css`, rebuild and check the generated CSS: + +```bash +make css-check +``` + +If you do not already have the Tailwind standalone binary, install it first: + +```bash +make install-tailwind +``` + +When a CSS source change is ready to commit, run: + +```bash +make release +``` + +That rebuilds and stages `assets/main.css`. Commit the source CSS and generated CSS together. + +## Pull Request Checklist + +- Explain the user-facing or theme-developer impact. +- Link the relevant workstream from [PLAN.md](PLAN.md) when possible. +- Include screenshots for storefront UI changes at desktop and mobile widths. +- Include the exact commands you ran and their results. +- Update docs when behavior, settings, events, public APIs, or release steps change. +- Keep pull requests focused. Separate docs polish, platform behavior, and storefront UI when they can land independently. + +## Public Issues And Support + +GitHub issue creation may be limited for this repository. If you can open an issue, use the templates and include reproduction steps, expected behavior, actual behavior, and the Spark version or commit. + +For security reports, do not open a public issue. Follow [SECURITY.md](SECURITY.md). + +For store-specific support, use your normal Next Commerce support channel and never post API keys, customer data, merchant configuration, or exploit details publicly. + +## Branching + +NextCommerceCo repositories use branch and pull request flow. Do not push directly to `main`. Keep generated artifacts such as `assets/main.css` in the same pull request as the source change that produced them. diff --git a/PLAN.md b/PLAN.md index 1a33f87..45ddd96 100644 --- a/PLAN.md +++ b/PLAN.md @@ -108,7 +108,7 @@ Spark should be ready if NEXT adds platform-level theme sections, but current Sp The public repository should stay easy for theme developers to understand, audit, and extend. - Keep `README.md`, `CLAUDE.md`, `PLAN.md`, and `docs/` accurate as Spark evolves. -- Add an "Extending Spark" guide for settings, partials, app hooks, and Web Components. +- Keep the "Extending Spark" guide current as settings, partials, app hooks, and Web Components evolve. - Keep Web Component events, attributes, slots, and public APIs documented in `docs/cart-events.md`, `docs/cart-rewards.md`, `docs/cart-drawer-architecture.md`, and future extension docs. - Add a DTL pattern catalog for Spark-specific gotchas. - Decide the marketplace/self-serve release package shape. diff --git a/README.md b/README.md index 534b24e..2a440b4 100644 --- a/README.md +++ b/README.md @@ -14,9 +14,26 @@ A modern starter theme for Next Commerce. Tailwind CSS v4, vanilla JS + Web Comp ## Quick Start -The compiled `assets/main.css` is committed to the repo, so NEXT developers can install Spark on a store without a local Tailwind toolchain. Clone the repo, point `ntk` at a store you control, and push. +The compiled `assets/main.css` is committed to the repo, so NEXT developers can inspect or install Spark without a local Tailwind toolchain. Choose the path that matches what you have available. -1. Install ntk and configure your store: +### Inspect Spark Locally + +Use this path when you want to evaluate the theme structure, docs, and generated CSS before connecting a store. + +```bash +git clone https://github.com/NextCommerceCo/spark.git +cd spark +python3 -m unittest discover -s tests +python3 scripts/sass-compat.py --check assets/main.css +``` + +Expected time: under 2 minutes after clone on a typical laptop. This verifies the committed CSS artifact and local tooling tests. It does not render a live storefront because Spark templates run inside the Next Commerce theme runtime. + +### Install On A Store + +Use this path when you have a Next Commerce store, API key, and theme id. + +1. Install `ntk` and configure your store: ```bash pip install next-theme-kit ntk init @@ -28,6 +45,8 @@ The compiled `assets/main.css` is committed to the repo, so NEXT developers can ntk push ``` +Expected time: 5-10 minutes if you already have store credentials. If `ntk` reports that `-a/--apikey` and `-s/--store` are required, create `config.yml` with `ntk init` or pass those flags explicitly. If Python prints a local OpenSSL or `urllib3` warning before `ntk` output, use a newer Python virtual environment; the warning comes from the local Python TLS stack, not from Spark. + For day-to-day development (editing CSS sources), set up Tailwind locally: ```bash @@ -129,6 +148,8 @@ Tracked theme documentation starts at [docs/README.md](docs/README.md). Current See [docs/theme-settings-partials.md](docs/theme-settings-partials.md) for the design-team catalog of Theme Settings partials and homepage section partials, [docs/figma-section-library-plan.md](docs/figma-section-library-plan.md) for the Spark Figma section library plan, [docs/performance-load-order.md](docs/performance-load-order.md) for the critical-path loading convention, [docs/pdp-customization.md](docs/pdp-customization.md) for the PDP redesign preservation checklist and QA runbook, [docs/pdp-variant-state.md](docs/pdp-variant-state.md) for the PDP variant state Interface, [docs/cart-events.md](docs/cart-events.md) for the cart event Interface, [docs/cart-rewards.md](docs/cart-rewards.md) for side-cart rewards and upsell rules, [docs/cart-drawer-architecture.md](docs/cart-drawer-architecture.md) for the drawer Module split, [docs/intro-bootstrap-comparison.md](docs/intro-bootstrap-comparison.md) for the Intro Bootstrap comparison, [docs/design-block-authoring.md](docs/design-block-authoring.md) for design-block authoring guidance, [docs/terminology.md](docs/terminology.md) for NEXT-native naming guardrails, and [docs/sections-architecture-proposal.md](docs/sections-architecture-proposal.md) for the future theme sections platform proposal. +Start with [docs/extending-spark.md](docs/extending-spark.md) when adding Theme Settings, homepage section partials, app hooks, Web Components, or public storefront behavior. + ## Design System All visual decisions are documented in [DESIGN.md](DESIGN.md) — typography, colors, spacing, motion, interaction states, accessibility, and anti-slop rules. Read it before making any UI change. @@ -137,7 +158,7 @@ All visual decisions are documented in [DESIGN.md](DESIGN.md) — typography, co The `.gitignore` file is intentionally committed. It documents local files that must stay out of the public repository, including store-specific `config.yml`, downloaded Tailwind binaries, tool session state, OS files, and editor settings. -See [SECURITY.md](SECURITY.md) for private vulnerability reporting and secrets-handling guidance. +See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution workflow, [CHANGELOG.md](CHANGELOG.md) for release notes, and [SECURITY.md](SECURITY.md) for private vulnerability reporting and secrets-handling guidance. ## License diff --git a/docs/README.md b/docs/README.md index ec72e3e..32d8c48 100644 --- a/docs/README.md +++ b/docs/README.md @@ -9,6 +9,7 @@ This directory contains Spark's theme-developer, design-team, and architecture d | [theme-settings-partials.md](theme-settings-partials.md) | Designers, theme developers | Catalog of Theme Settings-backed partials and template surfaces. | | [figma-section-library-plan.md](figma-section-library-plan.md) | Design team, theme developers | Plan for mapping Figma section components to Spark section authoring units. | | [section-specs/](section-specs/) | Design team, theme developers | Per-section specs for the current homepage section partials. | +| [extending-spark.md](extending-spark.md) | Theme developers, app developers | Supported extension surfaces for settings, partials, app hooks, events, and Web Components. | | [design-block-authoring.md](design-block-authoring.md) | Design team, theme developers | Guidance for adding or changing section-like design blocks. | | [performance-load-order.md](performance-load-order.md) | Theme developers, app developers | Critical-path load order for CSS, LCP preloads, scripts, app hooks, and tracking. | | [terminology.md](terminology.md) | Everyone | NEXT-native naming guardrails and Shopify migration mapping. | diff --git a/docs/extending-spark.md b/docs/extending-spark.md new file mode 100644 index 0000000..96e75b4 --- /dev/null +++ b/docs/extending-spark.md @@ -0,0 +1,97 @@ +# Extending Spark + +Spark is meant to be extended without forking the whole theme. This guide points to the supported extension surfaces and the files to update when you add one. + +## Choose The Right Extension Surface + +| Goal | Prefer | Start Here | +| --- | --- | --- | +| Add or change a homepage design block | Homepage section partial plus Theme Settings | `docs/design-block-authoring.md` | +| Add merchant-configurable theme behavior | `configs/settings_schema.json` and `configs/settings_data.json` | `docs/theme-settings-partials.md` | +| Integrate an app into storefront markup | `{% app_hook %}` slots | `docs/cart-events.md`, `docs/cart-drawer-architecture.md` | +| Coordinate cart UI behavior | DOM events through `SparkEvents` | `docs/cart-events.md` | +| Change PDP variant picker UI | Real controls named `attr_*` plus `SparkVariantState` | `docs/pdp-variant-state.md`, `docs/pdp-customization.md` | +| Add custom client-side behavior | Focused vanilla JS module or Web Component | Existing files in `assets/js/` | +| Change load order or head assets | Template blocks in `layouts/base.html` | `docs/performance-load-order.md` | + +## Theme Settings Extensions + +Theme Settings are global today and exposed to templates as `settings.*`. + +When adding a setting-backed surface: + +1. Add the setting to `configs/settings_schema.json`. +2. Add a default to `configs/settings_data.json`. +3. Use a stable prefix for related settings, such as `featured_products_*`. +4. Render the setting from a focused partial or template surface. +5. Update `docs/theme-settings-partials.md`. +6. Run JSON/schema parity checks if your branch adds them, then run the standard local checks. + +Keep future theme sections in mind. Settings that belong to one repeated section should be easy to move from `settings.foo` to future `section.settings.foo`. + +## Homepage Section Partials + +Homepage section partials are the current Spark design-block unit. They live in `partials/section_*.html` and are included from `templates/index.html` in a fixed order. + +Each public section should have: + +- A `show_*` toggle. +- Clear empty states for missing products, categories, images, links, or headings. +- Mobile-safe layout and copy behavior. +- A row in `docs/theme-settings-partials.md`. +- A spec under `docs/section-specs/` when the section is part of the maintained design library. + +Use shared helpers where possible: + +- `partials/section_heading.html` +- `partials/product_grid.html` +- `partials/cta_button.html` + +## App Hooks + +Spark exposes app integration points with `{% app_hook %}`. Apps should target those slots instead of editing theme files or reaching into private Web Component internals. + +Current hook examples live in product cards, PDP reviews, collection feeds, product detail surfaces, and global tracking points. Search for `{% app_hook %}` before adding a new hook. + +When adding a hook: + +1. Choose a stable, descriptive name. +2. Put the hook as close as possible to the DOM it extends. +3. Document the intended payload or surrounding markup contract. +4. Avoid names tied to one temporary app unless the hook is intentionally app-specific. + +## Cart And PDP Events + +Use events for behavior that crosses modules. + +Cart events are documented in `docs/cart-events.md`. Theme and app code should listen for `spark:cart:updated`, `spark:cart:added`, and `spark:cart:toggle` rather than mutating drawer internals. + +PDP selected variant behavior is documented in `docs/pdp-variant-state.md`. Custom picker designs should update real form controls named `attr_*` and listen for `spark:variant:changed` when they need to adapt gallery, price, or add-to-cart behavior. + +## JavaScript Modules And Web Components + +Spark JavaScript is vanilla, browser-loaded, and intentionally small. There is no bundler. + +When adding client-side code: + +- Keep modules focused and expose only the smallest useful public API on `window`. +- Prefer progressive enhancement. The page should still have useful server-rendered markup. +- Keep JS asset files ASCII-only. The platform processes JS through the template engine, so avoid `{%`, `{{`, Unicode punctuation, and non-ASCII symbols in comments or strings. +- Add tests when logic can be isolated without a full storefront runtime. + +## CSS And Generated Artifacts + +Author CSS in `css/input.css`. The storefront consumes `assets/main.css`. + +Before handoff: + +```bash +make css-check +python3 -m unittest discover -s tests +``` + +If you changed CSS sources, run `make release` and commit `assets/main.css` with the source change. + +## Release Notes + +Public-facing behavior changes should update [CHANGELOG.md](../CHANGELOG.md). Mention new settings, hooks, events, migration steps, and compatibility notes. A theme developer should be able to skim the changelog and understand whether their derived theme needs action. From bc4bb8b2002f920dafcff420969d17b046e3b013 Mon Sep 17 00:00:00 2001 From: Devin Michael Date: Fri, 19 Jun 2026 23:13:42 +0700 Subject: [PATCH 2/5] chore: retrigger review checks From b77da8c7b570993960b8c1e0454b4497d6cc015e Mon Sep 17 00:00:00 2001 From: Devin Michael Date: Sat, 20 Jun 2026 10:58:12 +0700 Subject: [PATCH 3/5] chore: retry Kilo review From c0cbd3c0e20f68d28afffc432b9c65b97e8b715e Mon Sep 17 00:00:00 2001 From: Devin Michael Date: Sat, 20 Jun 2026 11:04:24 +0700 Subject: [PATCH 4/5] docs: address Kilo review feedback --- .github/ISSUE_TEMPLATE/bug_report.yml | 3 +++ .github/ISSUE_TEMPLATE/config.yml | 3 +++ .github/ISSUE_TEMPLATE/dx_feedback.yml | 2 +- .github/workflows/ci.yml | 27 ++++++++++++++++++++++++++ CHANGELOG.md | 2 +- CONTRIBUTING.md | 6 ++++-- README.md | 7 ++++++- docs/README.md | 2 +- docs/extending-spark.md | 8 ++++---- 9 files changed, 50 insertions(+), 10 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index d951b02..c56456a 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -51,6 +51,7 @@ body: - Homepage section partial - Product detail page - Cart or side cart + - Web Component - App hook - CSS build or compatibility - Documentation @@ -65,3 +66,5 @@ body: placeholder: | python3 -m unittest discover -s tests python3 scripts/sass-compat.py --check assets/main.css + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 1441621..40cfacf 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,5 +1,8 @@ blank_issues_enabled: false contact_links: + - name: Store-specific support + url: https://github.com/NextCommerceCo/spark/blob/main/CONTRIBUTING.md#public-issues-and-support + about: Use your normal Next Commerce support channel for merchant-specific store issues. - name: Security reports url: https://github.com/NextCommerceCo/spark/security/advisories/new about: Report vulnerabilities privately. Do not open public issues with exploit details or secrets. diff --git a/.github/ISSUE_TEMPLATE/dx_feedback.yml b/.github/ISSUE_TEMPLATE/dx_feedback.yml index 9923402..0af738b 100644 --- a/.github/ISSUE_TEMPLATE/dx_feedback.yml +++ b/.github/ISSUE_TEMPLATE/dx_feedback.yml @@ -46,4 +46,4 @@ body: id: time_lost attributes: label: Time lost - placeholder: "About 10 minutes" + placeholder: "e.g., about 10 minutes" diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 69579a6..650092f 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -6,6 +6,13 @@ on: branches: - main +permissions: + contents: read + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + jobs: verify: name: Verify theme tooling @@ -25,8 +32,28 @@ jobs: with: node-version: "22" + - name: Install CI dependencies + run: | + python3 -m pip install --upgrade pip + python3 -m pip install pyyaml + + - name: Validate GitHub YAML + run: | + python3 - <<'PY' + from pathlib import Path + import yaml + + for path in sorted(Path(".github").glob("**/*.yml")): + with path.open() as handle: + yaml.safe_load(handle) + print(f"OK: {path}") + PY + - name: Run tests run: python3 -m unittest discover -s tests + - name: Run JavaScript module tests + run: node tests/js/membership-pricing.test.js + - name: Check committed CSS compatibility run: python3 scripts/sass-compat.py --check assets/main.css diff --git a/CHANGELOG.md b/CHANGELOG.md index 98f26c2..3dc113a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,7 @@ All notable public Spark changes should be recorded here. Spark follows human-readable release notes rather than a strict package-manager version contract. The current public version is shown in [README.md](README.md). When releasing a new version, update the README version, add a dated changelog section, and publish a Git tag or GitHub release when the repo is ready for external consumers to pin versions. -## Unreleased +## 1.1.2 - Unreleased - Clarified the first-run path for local inspection versus installing Spark on a real Next Commerce store. - Added contribution guidance, issue templates, CI checks, and an extension guide for theme developers. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4d3fdfc..f58d3fe 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -18,6 +18,8 @@ python3 -m unittest discover -s tests python3 scripts/sass-compat.py --check assets/main.css ``` +The standard local checks do not need extra Python packages. CI also validates GitHub workflow and issue-template YAML with PyYAML; install `pyyaml` first if you run that optional check locally. + If you change `css/input.css`, rebuild and check the generated CSS: ```bash @@ -41,7 +43,7 @@ That rebuilds and stages `assets/main.css`. Commit the source CSS and generated ## Pull Request Checklist - Explain the user-facing or theme-developer impact. -- Link the relevant workstream from [PLAN.md](PLAN.md) when possible. +- Name the relevant [PLAN.md](PLAN.md) workstream when it applies; otherwise explain the public DX or user impact in plain language. - Include screenshots for storefront UI changes at desktop and mobile widths. - Include the exact commands you ran and their results. - Update docs when behavior, settings, events, public APIs, or release steps change. @@ -49,7 +51,7 @@ That rebuilds and stages `assets/main.css`. Commit the source CSS and generated ## Public Issues And Support -GitHub issue creation may be limited for this repository. If you can open an issue, use the templates and include reproduction steps, expected behavior, actual behavior, and the Spark version or commit. +Use the GitHub issue templates for reproducible bugs and developer-experience feedback. Include reproduction steps, expected behavior, actual behavior, and the Spark version or commit. If issue creation is unavailable for your account or the topic is store-specific, use your normal Next Commerce support channel. For security reports, do not open a public issue. Follow [SECURITY.md](SECURITY.md). diff --git a/README.md b/README.md index 2a440b4..2a4dc5d 100644 --- a/README.md +++ b/README.md @@ -45,7 +45,7 @@ Use this path when you have a Next Commerce store, API key, and theme id. ntk push ``` -Expected time: 5-10 minutes if you already have store credentials. If `ntk` reports that `-a/--apikey` and `-s/--store` are required, create `config.yml` with `ntk init` or pass those flags explicitly. If Python prints a local OpenSSL or `urllib3` warning before `ntk` output, use a newer Python virtual environment; the warning comes from the local Python TLS stack, not from Spark. +Expected time: 5-10 minutes if you already have store credentials. If `ntk` cannot find credentials, create `config.yml` with `ntk init`, copy `config.example.yml`, or pass credentials through the CLI options shown by `ntk --help`. For day-to-day development (editing CSS sources), set up Tailwind locally: @@ -72,6 +72,11 @@ When you change `css/input.css` (or any source that affects the build), run `mak | `make release` | Rebuild minified `assets/main.css` and stage it for commit | | `make dev` | Legacy: run Tailwind watcher + ntk watcher in parallel | +## Troubleshooting + +- Credential errors from `ntk`: confirm `config.yml` has the API key, store domain, and theme id for a store you control. +- Python runtime warnings before `ntk` output: retry from a current Python virtual environment. These warnings usually come from local Python packaging, not Spark. + ## CSS Compatibility Verification Spark authoring CSS can use Tailwind v4 constructs in `css/input.css`, but the storefront platform sees the generated artifact in `assets/main.css`. Before uploading CSS, run: diff --git a/docs/README.md b/docs/README.md index 32d8c48..b19058f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,10 +6,10 @@ This directory contains Spark's theme-developer, design-team, and architecture d | Doc | Audience | Purpose | | --- | --- | --- | +| [extending-spark.md](extending-spark.md) | Theme developers, app developers | Supported extension surfaces for settings, partials, app hooks, events, and Web Components. | | [theme-settings-partials.md](theme-settings-partials.md) | Designers, theme developers | Catalog of Theme Settings-backed partials and template surfaces. | | [figma-section-library-plan.md](figma-section-library-plan.md) | Design team, theme developers | Plan for mapping Figma section components to Spark section authoring units. | | [section-specs/](section-specs/) | Design team, theme developers | Per-section specs for the current homepage section partials. | -| [extending-spark.md](extending-spark.md) | Theme developers, app developers | Supported extension surfaces for settings, partials, app hooks, events, and Web Components. | | [design-block-authoring.md](design-block-authoring.md) | Design team, theme developers | Guidance for adding or changing section-like design blocks. | | [performance-load-order.md](performance-load-order.md) | Theme developers, app developers | Critical-path load order for CSS, LCP preloads, scripts, app hooks, and tracking. | | [terminology.md](terminology.md) | Everyone | NEXT-native naming guardrails and Shopify migration mapping. | diff --git a/docs/extending-spark.md b/docs/extending-spark.md index 96e75b4..7835845 100644 --- a/docs/extending-spark.md +++ b/docs/extending-spark.md @@ -8,7 +8,7 @@ Spark is meant to be extended without forking the whole theme. This guide points | --- | --- | --- | | Add or change a homepage design block | Homepage section partial plus Theme Settings | `docs/design-block-authoring.md` | | Add merchant-configurable theme behavior | `configs/settings_schema.json` and `configs/settings_data.json` | `docs/theme-settings-partials.md` | -| Integrate an app into storefront markup | `{% app_hook %}` slots | `docs/cart-events.md`, `docs/cart-drawer-architecture.md` | +| Integrate an app into storefront markup | `{% app_hook %}` slots | `docs/terminology.md`, `docs/performance-load-order.md` | | Coordinate cart UI behavior | DOM events through `SparkEvents` | `docs/cart-events.md` | | Change PDP variant picker UI | Real controls named `attr_*` plus `SparkVariantState` | `docs/pdp-variant-state.md`, `docs/pdp-customization.md` | | Add custom client-side behavior | Focused vanilla JS module or Web Component | Existing files in `assets/js/` | @@ -22,10 +22,10 @@ When adding a setting-backed surface: 1. Add the setting to `configs/settings_schema.json`. 2. Add a default to `configs/settings_data.json`. -3. Use a stable prefix for related settings, such as `featured_products_*`. +3. Use a stable prefix for related settings. For example, the featured products section keeps its toggle, content, and style controls under `show_featured_products` and `featured_products_*`; see [configs/settings_schema.json](../configs/settings_schema.json) and [partials/section_featured_products.html](../partials/section_featured_products.html). 4. Render the setting from a focused partial or template surface. 5. Update `docs/theme-settings-partials.md`. -6. Run JSON/schema parity checks if your branch adds them, then run the standard local checks. +6. Run the standard local checks. If your branch adds a schema validation script, add it to [CONTRIBUTING.md](../CONTRIBUTING.md) and CI before referencing it here. Keep future theme sections in mind. Settings that belong to one repeated section should be easy to move from `settings.foo` to future `section.settings.foo`. @@ -76,7 +76,7 @@ When adding client-side code: - Keep modules focused and expose only the smallest useful public API on `window`. - Prefer progressive enhancement. The page should still have useful server-rendered markup. -- Keep JS asset files ASCII-only. The platform processes JS through the template engine, so avoid `{%`, `{{`, Unicode punctuation, and non-ASCII symbols in comments or strings. +- Keep JS asset files ASCII-only; see [CLAUDE.md](../CLAUDE.md#critical-js-asset-files). The platform processes JS through DTL, so `{%`, `{{`, Unicode punctuation, and non-ASCII symbols can be parsed as template syntax or trigger CDN 500s. - Add tests when logic can be isolated without a full storefront runtime. ## CSS And Generated Artifacts From d28700d4f3bd0bd73a293b89de4fe122e6f03853 Mon Sep 17 00:00:00 2001 From: Devin Michael Date: Sat, 20 Jun 2026 13:01:46 +0700 Subject: [PATCH 5/5] docs: clean up remaining review feedback --- .github/workflows/ci.yml | 15 +++++++++------ README.md | 9 +++------ 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 650092f..16fd501 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -34,12 +34,12 @@ jobs: - name: Install CI dependencies run: | - python3 -m pip install --upgrade pip - python3 -m pip install pyyaml + python -m pip install --upgrade pip + python -m pip install pyyaml - name: Validate GitHub YAML run: | - python3 - <<'PY' + python - <<'PY' from pathlib import Path import yaml @@ -50,10 +50,13 @@ jobs: PY - name: Run tests - run: python3 -m unittest discover -s tests + run: python -m unittest discover -s tests - name: Run JavaScript module tests - run: node tests/js/membership-pricing.test.js + run: | + for test_file in tests/js/*.test.js; do + node "$test_file" + done - name: Check committed CSS compatibility - run: python3 scripts/sass-compat.py --check assets/main.css + run: python scripts/sass-compat.py --check assets/main.css diff --git a/README.md b/README.md index 2a4dc5d..26dd92a 100644 --- a/README.md +++ b/README.md @@ -72,11 +72,6 @@ When you change `css/input.css` (or any source that affects the build), run `mak | `make release` | Rebuild minified `assets/main.css` and stage it for commit | | `make dev` | Legacy: run Tailwind watcher + ntk watcher in parallel | -## Troubleshooting - -- Credential errors from `ntk`: confirm `config.yml` has the API key, store domain, and theme id for a store you control. -- Python runtime warnings before `ntk` output: retry from a current Python virtual environment. These warnings usually come from local Python packaging, not Spark. - ## CSS Compatibility Verification Spark authoring CSS can use Tailwind v4 constructs in `css/input.css`, but the storefront platform sees the generated artifact in `assets/main.css`. Before uploading CSS, run: @@ -91,8 +86,10 @@ Known risky generated CSS includes `@supports`, `@property`, `@layer`, `oklch()` Avoid dynamic Tailwind class construction in templates. Tailwind scans source files at build time, so classes like `bg-{{ settings.primary_color }}` are never emitted. Use CSS custom properties (`bg-[var(--primary-color)]`) or static conditional classes instead. -Troubleshooting quick read: +## Troubleshooting +- Credential errors from `ntk`: confirm `config.yml` has the API key, store domain, and theme id for a store you control. +- Python runtime warnings before `ntk` output: retry from a current Python virtual environment. These warnings usually come from local Python packaging, not Spark. - Local Tailwind/build failure: `make css` fails before `assets/main.css` is written. Fix `css/input.css`, missing Tailwind binary, or local command setup. - Platform Sass/compiler failure: local build passes but upload/storefront errors mention CSS parsing. Run `make css-check` and inspect any unsupported construct it reports. - Missing uploaded compiled CSS: templates changed but styling did not. Rebuild with `make css-check`, then push `assets/main.css` explicitly.