better-horizon

Imported from muneebbug/better-horizon (AGENTS.md). Install upstream with npx skills add muneebbug/better-horizon. Copyright stays with the author.

AI Agent Instructions for Better Horizon

Welcome to the Better Horizon codebase — a first-party Shopify theme built with modern Liquid Storefronts, native Theme Blocks, Web Components, and strict accessibility standards.

This file serves as the master guide for all AI coding agents working on this repository. All detailed rules, standards, and component patterns are modularly organized inside .cursor/rules/. Agents must consult and follow the corresponding rule files when working in specific areas of the codebase.

🧭 Quick Rule Navigator

Before making changes, identify the relevant files you are modifying and refer to the corresponding rule files in .cursor/rules/:

1. Core Architecture & Shopify Templating

2. Frontend Web Standards & Code Quality

3. Global Accessibility Standards (WCAG 2.2 AA)

4. Interactive Component Accessibility Patterns

5. Workflow & Continuous Documentation

⚡ Non-Negotiable Directives for AI Agents

1. ⚠️ Schema Editing Rules

• NEVER edit the {% schema %} block directly in .liquid files if the schema is managed via source files in the schemas/ directory.
• Edit the corresponding source file in schemas/ and run pnpm run build:schemas (or npm run build:schemas) to regenerate the schema in the Liquid files.
• Refer to .cursor/rules/schemas.mdc for detailed schema configurations.

2. ♿ Strict WCAG 2.2 AA Accessibility Compliance

• Every interactive element must be keyboard operable (Tab, Enter, Space, Arrows, Escape).
• Never remove focus outlines without providing an accessible alternative. Use high-contrast focus rings.
• Ensure all interactive touch targets meet the minimum 44×44px or 24×24px spacing requirements.
• Always use semantic HTML first (<button>, <a>, <dialog>, <details>, <nav>, <header>, <main>) rather than <div> with click listeners.

3. 🧩 Theme Blocks & Liquid Architecture

• Horizon utilizes Shopify Theme Blocks. Blocks are reusable components placed via {% content_for 'block', type: 'block-name', id: 'unique-id' %}.
• Keep components modular. Pass data into snippets using render 'snippet-name', prop: value (never use deprecated include).
• Scoped CSS specific to a block or section should live inside {% stylesheet %} blocks or dedicated assets. Shared global styles belong in assets/base.css.
• Refer to .cursor/rules/blocks.mdc and .cursor/rules/sections.mdc.

4. 🌐 Web Components & Native JavaScript

• Horizon favors native Web Components (Custom Elements extending HTMLElement) for UI behaviors.
• Write vanilla JavaScript with progressive enhancement in mind. Ensure the server-rendered HTML is accessible even before JavaScript executes.
• Refer to .cursor/rules/javascript-standards.mdc.

5. 📝 Living Documentation Maintenance

• All agents are required to keep .cursor/prompts/ and .cursor/references/ updated as living documents whenever new patterns, edge cases, or solutions are discovered.
• Refer to .cursor/rules/prompts-and-references.mdc.

📁 Repository Overview

better-horizon/
├── .cursor/
│   └── rules/                  # Complete library of 44 .mdc rule definitions
├── assets/                     # CSS stylesheets, vanilla JS scripts, SVGs, and fonts
├── blocks/                     # Theme block Liquid templates
├── config/
│   └── settings_schema.json    # Global theme configuration settings schema
├── layout/                     # Main theme layout templates (e.g. theme.liquid)
├── locales/                    # Translation JSON dictionaries (en.default.json, etc.)
├── sections/                   # Shopify section Liquid templates
├── snippets/                   # Reusable Liquid snippet components
├── templates/                  # JSON page, product, collection, and blog templates
├── AGENTS.md                   # This master agent instructions file
└── README.md                   # Project overview and Shopify CLI getting started