Block first experiments

AGENTS.md

@@ -0,0 +1,90 @@
+# Skeleton Theme Agent Guide
+
+A minimal Shopify Liquid theme built on block-first agentic composition. This
+file captures the dialect an external coding agent is most likely to miss. Code
+is the source of truth.
+
+## Non-negotiables when editing this theme
+
+- **No sections:** no `sections/` folder, no `{% section %}`/`{% sections %}`
+  tags, no JSON templates, no schema `presets`.
+- **No Liquid-embedded assets:** no `{% stylesheet %}`, no `{% javascript %}`.
+  All CSS lives in `assets/critical.css`.
+- **Block-first composition:** templates compose page content directly from
+  blocks, snippets, and inline markup. Do not introduce single-use page
+  sections.
+- **Container-owned layout:** each page region is wrapped in the `container`
+  block, which owns the outer layout element.
+- **Whitespace matters:** include whitespace between an HTML tag name and a
+  following Liquid delimiter (`<li {% ... %}`, not `<li{% ... %}`).
+- **Translated UI only:** every user-facing string uses a literal
+  `{{ 'key' | t }}` call.
+- **Shopify routes for storefront URLs:** use Liquid `routes.*` for every
+  storefront path; never hardcode `/cart`, `/search`, or `/collections`.
+
+## Composition model
+
+```
+templates/*.liquid → {% block 'container' %} → blocks / snippets / inline markup
+```
+
+Templates are the composition root. `container` is the block every template composes.
+
+## The block tag
+
+```liquid
+{% block 'name', kwargs %}body{% endblock %}
+```
+
+- Renders `blocks/name.liquid` inline; the body flows to `{{ block.content }}`
+  inside that block.
+- **Never self-closing** — always paired with `{% endblock %}`.
+- Kwargs pass the `tag` param and dotted settings overrides
+  (`block.settings.<id>: value`).
+- The dialect also defines reserved `class`/`attributes` kwargs, but skeleton's
+  plain-CSS blocks do not declare them (see Blocks below).
+
+## The partial tag
+
+```liquid
+{% partial 'name' %}...{% endpartial %}
+```
+
+Partials are named inline regions — not files — that client JavaScript can
+fetch and patch for server-backed DOM updates. Partial names are contracts with
+that JS.
+
+**Skeleton intentionally omits partials.** It has no JS-refetched dynamic
+region, so introducing a partial would mean introducing client JS that the
+minimalism guardrail forbids. Add one only when a genuine dynamic region needs
+it.
+
+## Blocks
+
+Required shape:
+- A `{% doc %}` header with typed params and a `{% schema %}` tag **without
+  `presets`**.
+- Declare only block-specific `@param`s such as `tag`. Do **not** declare the
+  reserved `class`/`attributes` kwargs as `@param`.
+- Render `{{ block.content }}` where the block composes caller-supplied body.
+- Keep `{{ block.shopify_attributes }}` on the root element for editor support.
+
+Skeleton keeps `.theme-check.yml` as a pristine
+`extends: theme-check:recommended` with **zero overrides**. Blocks parameterize
+via `tag` + `block.settings.*` and rely on `{{ block.shopify_attributes }}` —
+no reserved-name workaround is needed.
+
+Public blocks are usable anywhere; a leading underscore (`_private`) marks
+context-specific sub-components.
+
+Current blocks: `container`, `hello-world`, `text`, `header`, `footer`.
+
+## Theme map
+
+```
+blocks/               container, hello-world, text, header, footer
+templates/            *.liquid composition roots (no JSON)
+layout/               theme.liquid shell composing header/footer blocks
+snippets/             internal utilities (css-variables, image, meta-tags)
+assets/critical.css   all theme CSS
+```

README.md

@@ -1,160 +1,129 @@
-<h1 align="center" style="position: relative;">
-  <br>
-    <img src="./assets/shoppy-x-ray.svg" alt="logo" width="200">
-  <br>
-  Shopify Skeleton Theme
-</h1>
-
-A minimal, carefully structured Shopify theme designed to help you quickly get started. Designed with modularity, maintainability, and Shopify's best practices in mind.
-
-<p align="center">
-  <a href="./LICENSE.md"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License"></a>
-  <a href="./actions/workflows/ci.yml"><img alt="CI" src="https://github.com/Shopify/skeleton-theme/actions/workflows/ci.yml/badge.svg"></a>
-</p>
-
-## Getting started
-
-### Prerequisites
-
-Before starting, ensure you have the latest Shopify CLI installed:
-
-- [Shopify CLI](https://shopify.dev/docs/api/shopify-cli) – helps you download, upload, preview themes, and streamline your workflows
-
-If you use VS Code:
-
-- [Shopify Liquid VS Code Extension](https://shopify.dev/docs/storefronts/themes/tools/shopify-liquid-vscode) – provides syntax highlighting, linting, inline documentation, and auto-completion specifically designed for Liquid templates
-
-### Clone
-
-Clone this repository using Git or Shopify CLI:
-
-```bash
-git clone git@github.com:Shopify/skeleton-theme.git
-# or
-shopify theme init
-```
-
-### Preview
-
-Preview this theme using Shopify CLI:
-
-```bash
-shopify theme dev
-```
-
-## Theme architecture
-
-```bash
-.
-├── assets          # Stores static assets (CSS, JS, images, fonts, etc.)
-├── blocks          # Reusable, nestable, customizable UI components
-├── config          # Global theme settings and customization options
-├── layout          # Top-level wrappers for pages (layout templates)
-├── locales         # Translation files for theme internationalization
-├── sections        # Modular full-width page components
-├── snippets        # Reusable Liquid code or HTML fragments
-└── templates       # Templates combining sections to define page structures
-```
-
-To learn more, refer to the [theme architecture documentation](https://shopify.dev/docs/storefronts/themes/architecture).
-
-### Templates
-
-[Templates](https://shopify.dev/docs/storefronts/themes/architecture/templates#template-types) control what's rendered on each type of page in a theme.
-
-The Skeleton Theme scaffolds [JSON templates](https://shopify.dev/docs/storefronts/themes/architecture/templates/json-templates) to make it easy for merchants to customize their store.
-
-None of the template types are required, and not all of them are included in the Skeleton Theme. Refer to the [template types reference](https://shopify.dev/docs/storefronts/themes/architecture/templates#template-types) for a full list.
-
-### Sections
-
-[Sections](https://shopify.dev/docs/storefronts/themes/architecture/sections) are Liquid files that allow you to create reusable modules of content that can be customized by merchants. They can also include blocks which allow merchants to add, remove, and reorder content within a section.
-
-Sections are made customizable by including a `{% schema %}` in the body. For more information, refer to the [section schema documentation](https://shopify.dev/docs/storefronts/themes/architecture/sections/section-schema).
-
-### Blocks
-
-[Blocks](https://shopify.dev/docs/storefronts/themes/architecture/blocks) let developers create flexible layouts by breaking down sections into smaller, reusable pieces of Liquid. Each block has its own set of settings, and can be added, removed, and reordered within a section.
-
-Blocks are made customizable by including a `{% schema %}` in the body. For more information, refer to the [block schema documentation](https://shopify.dev/docs/storefronts/themes/architecture/blocks/theme-blocks/schema).
-
-## Schemas
-
-When developing components defined by schema settings, we recommend these guidelines to simplify your code:
-
-- **Single property settings**: For settings that correspond to a single CSS property, use CSS variables:
-
-  ```liquid
-  <div class="collection" style="--gap: {{ block.settings.gap }}px">
-    ...
-  </div>
-
-  {% stylesheet %}
-    .collection {
-      gap: var(--gap);
-    }
-  {% endstylesheet %}
-
-  {% schema %}
-  {
-    "settings": [{
-      "type": "range",
-      "label": "gap",
-      "id": "gap",
-      "min": 0,
-      "max": 100,
-      "unit": "px",
-      "default": 0,
-    }]
-  }
-  {% endschema %}
-  ```
-
-- **Multiple property settings**: For settings that control multiple CSS properties, use CSS classes:
-
-  ```liquid
-  <div class="collection {{ block.settings.layout }}">
-    ...
-  </div>
-
-  {% stylesheet %}
-    .collection--full-width {
-      /* multiple styles */
-    }
-    .collection--narrow {
-      /* multiple styles */
-    }
-  {% endstylesheet %}
-
-  {% schema %}
-  {
-    "settings": [{
-      "type": "select",
-      "id": "layout",
-      "label": "layout",
-      "values": [
-        { "value": "collection--full-width", "label": "t:options.full" },
-        { "value": "collection--narrow", "label": "t:options.narrow" }
-      ]
-    }]
-  }
-  {% endschema %}
-  ```
-
-## CSS & JavaScript
-
-For CSS and JavaScript, we recommend using the [`{% stylesheet %}`](https://shopify.dev/docs/api/liquid/tags#stylesheet) and [`{% javascript %}`](https://shopify.dev/docs/api/liquid/tags/javascript) tags. They can be included multiple times, but the code will only appear once.
-
-### `critical.css`
-
-The Skeleton Theme explicitly separates essential CSS necessary for every page into a dedicated `critical.css` file.
-
-## Contributing
-
-We're excited for your contributions to the Skeleton Theme! This repository aims to remain as lean, lightweight, and fundamental as possible, and we kindly ask your contributions to align with this intention.
-
-Visit our [CONTRIBUTING.md](./CONTRIBUTING.md) for a detailed overview of our process, guidelines, and recommendations.
-
-## License
-
-Skeleton Theme is open-sourced under the [MIT](./LICENSE.md) License.
+<h1 align="center" style="position: relative;">
+  <br>
+    <img src="./assets/shoppy-x-ray.svg" alt="logo" width="200">
+  <br>
+  Shopify Skeleton Theme
+</h1>
+
+A minimal Shopify theme built on block-first composition. Templates compose each
+page directly from blocks, snippets, and inline markup — no sections, no JSON
+templates. It's designed to stay lean and to be edited by coding agents as
+readily as by people.
+
+<p align="center">
+  <a href="./LICENSE.md"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License"></a>
+  <a href="./actions/workflows/ci.yml"><img alt="CI" src="https://github.com/Shopify/skeleton-theme/actions/workflows/ci.yml/badge.svg"></a>
+</p>
+
+## Getting started
+
+### Prerequisites
+
+Before starting, ensure you have the latest Shopify CLI installed:
+
+- [Shopify CLI](https://shopify.dev/docs/api/shopify-cli) – helps you download, upload, preview themes, and streamline your workflows
+
+If you use VS Code:
+
+- [Shopify Liquid VS Code Extension](https://shopify.dev/docs/storefronts/themes/tools/shopify-liquid-vscode) – provides syntax highlighting, linting, inline documentation, and auto-completion specifically designed for Liquid templates
+
+### Clone
+
+Clone this repository using Git or Shopify CLI:
+
+```bash
+git clone git@github.com:Shopify/skeleton-theme.git
+# or
+shopify theme init
+```
+
+### Preview
+
+Preview this theme using Shopify CLI:
+
+```bash
+shopify theme dev
+```
+
+## Theme architecture
+
+```bash
+.
+├── assets          # Static assets, including critical.css (all theme CSS)
+├── blocks          # Reusable, nestable, customizable UI components
+├── config          # Global theme settings and customization options
+├── layout          # Top-level page wrappers
+├── locales         # Translation files for theme internationalization
+├── snippets        # Reusable Liquid code or HTML fragments
+└── templates       # Liquid composition roots, one per page type
+```
+
+To learn more, refer to the [theme architecture documentation](https://shopify.dev/docs/storefronts/themes/architecture).
+
+## Block-first composition
+
+Every page is composed from blocks. The composition flows in one direction:
+
+```
+templates/*.liquid → {% block 'container' %} → blocks / snippets / inline markup
+```
+
+### Templates
+
+[Templates](https://shopify.dev/docs/storefronts/themes/architecture/templates#template-types)
+control what's rendered on each type of page. In this theme they are Liquid
+files (`templates/*.liquid`), not JSON. Each template is a composition root: it
+wraps its page content in the `container` block and composes the rest from
+blocks and inline markup.
+
+For example, `templates/index.liquid` composes the `hello-world` block inside a
+container:
+
+```liquid
+{% block 'container', tag: 'div' %}
+  {% block 'hello-world' %}{% endblock %}
+{% endblock %}
+```
+
+### Blocks
+
+[Blocks](https://shopify.dev/docs/storefronts/themes/architecture/blocks) are
+the theme's building units. Each block is a single file in `blocks/`, opens with
+a `{% doc %}` header describing its parameters, and ends with a `{% schema %}`
+(no `presets`). A block renders caller-supplied content through
+`{{ block.content }}` and keeps `{{ block.shopify_attributes }}` on its root
+element for theme-editor support.
+
+The `container` block owns each page's outer layout element; `blocks/hello-world.liquid`
+is the theme's starter demo block. `layout/theme.liquid` composes the `header`
+and `footer` blocks directly, keeping the layout a thin shell.
+
+## Non-negotiables
+
+This theme deliberately excludes the section-based model. When editing it:
+
+- No `sections/` directory, and no `{% section %}` / `{% sections %}` tags.
+- No JSON templates and no schema `presets`.
+- No Liquid-embedded assets: keep CSS in `assets/critical.css` rather than
+  `{% stylesheet %}` / `{% javascript %}` blocks.
+- Compose pages from blocks and inline markup, not single-use page sections.
+
+[`AGENTS.md`](./AGENTS.md) is the source of truth for the theme's dialect and the
+full set of rules coding agents follow.
+
+## CSS
+
+All theme CSS lives in [`assets/critical.css`](./assets/critical.css), loaded
+once from `layout/theme.liquid`. Keeping styles in one file — rather than
+embedding them in Liquid — preserves the theme's minimalism and keeps blocks
+markup-only.
+
+## Contributing
+
+We're excited for your contributions to the Skeleton Theme! This repository aims to remain as lean, lightweight, and fundamental as possible, and we kindly ask your contributions to align with this intention.
+
+Visit our [CONTRIBUTING.md](./CONTRIBUTING.md) for a detailed overview of our process, guidelines, and recommendations.
+
+## License
+
+Skeleton Theme is open-sourced under the [MIT](./LICENSE.md) License.