Jay Stack Agent Kit

Designer Agent Kit — documentation written for AI agents, readable by humans.

This folder contains everything you need to create jay-html pages for a jay-stack application.

What is Jay Stack?

Jay Stack is a full-stack framework where:

Plugins provide headless components (data + interactions, no UI)
Contracts define the data shape and interaction points of each component
jay-html templates provide the UI that binds to contract data
Rendering phases determine when data is available (build-time, request-time, client-side)

Your job is to create .jay-html pages that bind to the data and interactions defined by contracts. All visible UI structure belongs in jay-html — not in page.ts via document.createElement. Behavior and state live in page.ts; elements are reached through refs declared in the template.

Rendering Phases

Phase	When	Use For
slow	Build time (SSG)	Static content, SEO data, pre-rendered lists
fast	Request time (SSR)	Per-request data (prices, stock, personalization)
fast+interactive	Request + client	Data that also updates on the client

There is no standalone "interactive" phase. Any tag with type: interactive (refs/interactions) is automatically fast+interactive. Tags without an explicit phase are available in all phases.

Workflow

Read this file for overview and workflow
Discover plugins — read plugins-index.yaml to see available plugins, contracts, and actions.
Read contracts — read the .jay-contract files (paths from plugins-index) to understand data shapes, tag types, phases, and props.
Read actions — read .jay-action files (paths from plugins-index) to see action descriptions, input schemas, and output schemas. This tells you what data each action accepts and returns.
Read references — check references/<plugin>/ for pre-generated discovery data (product catalogs, collection schemas, etc.). These are generated by jay-stack agent-kit and contain real data from the site.
Discover data — run jay-stack params <plugin>/<contract> for SSG route params, jay-stack action <plugin>/<action> for data discovery. Use reference files (step 5) first when available — they're faster than running CLI commands.
Create pages — write .jay-html files under src/pages/ following directory-based routing. For static override routes (a static page that overrides a dynamic route for a specific URL), declare params with <script type="application/jay-params">.
Validate — run jay-stack validate to check for errors.
Test — run jay-stack dev --test-mode and verify pages render.

Reference Docs

File	Topic
project-structure.md	Project layout, styling patterns (CSS themes, design tokens), configuration files
jay-html-syntax.md	Jay-HTML overview: philosophy, component types, nesting rules, links to sub-files
jay-html-template-syntax.md	Template markup: data binding, conditions (boolean, enum, numeric, &&/\|\|), loops, refs
jay-html-components.md	Component imports: headless (key/instance), headfull FS, nesting patterns
jay-html-styling.md	Styling: inline, external, dynamic style bindings, class bindings
routing.md	Directory-based routing: page structure, dynamic routes, route priority
navigation-patterns.md	Active menu/sidebar patterns using `jay.url.path`, `===`, and `^=` operators
contracts-and-plugins.md	Reading contracts, plugin.yaml, .jay-action files, and the materialized indexes
Contract Authoring Guide	Writing contracts: syntax, page/component/linked contracts, examples
script-tags.md	Script tag policy: use page.ts for behavior, jay-script="allow" for third-party scripts
cli-commands.md	CLI commands: setup, validate, params, action, dev server
`../references/<plugin>/`	Pre-generated discovery data: product catalogs, collection schemas (from `jay-stack agent-kit`)

When to Use Headfull Components

Use headfull full-stack components for shared UI sections that should look the same across pages — headers, navigation menus, footers, sidebars. These are placed in src/components/ and imported into any page that needs them. This keeps the shared layout in one place: update the component once and every page reflects the change.

If a section is unique to a single page, write it directly in the page's .jay-html — no component needed.

See jay-html-components.md for import syntax and component structure.

Quick Start

1. Discover plugins and contracts

Read plugins-index.yaml:

plugins:
  - name: wix-stores
    path: ./node_modules/@wix/stores
    contracts:
      - name: product-page
        type: static
        path: ./node_modules/@wix/stores/lib/contracts/product-page.jay-contract
    actions:
      - name: searchProducts
        description: Search products with text/filter/sort/pagination
        path: ./node_modules/@wix/stores/lib/actions/search-products.jay-action

2. Read a contract

The .jay-contract file at the path from the index defines the data shape:

name: ProductWidget
props:
  - name: productId
    type: string
    required: true
tags:
  - tag: name
    type: data
    dataType: string
    phase: slow
  - tag: inStock
    type: variant
    dataType: boolean
    phase: fast+interactive
  - tag: addToCart
    type: interactive
    elementType: HTMLButtonElement

3. Create a page

Create src/pages/page.jay-html:

<html>
  <head>
    <script
      type="application/jay-headless"
      plugin="wix-stores"
      contract="product-page"
      key="product"
    ></script>
  </head>
  <body>
    <h1>{product.name}</h1>
    <span if="product.inStock">In Stock</span>
    <button ref="product.addToCart">Add to Cart</button>
  </body>
</html>

4. Validate and run

jay-stack validate
jay-stack dev

Plugin-Contributed Guides

File	Plugin	Description
markdown-usage.md	markdown	The `@jay-framework/markdown` plugin renders markdown content as HTML in jay-html pages. It provides three headless components.
accordion.md	ui-kit	Collapsible sections using native `<details>` / `<summary>`. Pure HTML, no component needed.
click-popover.md	ui-kit	Popup dialog on button click with auto-dismiss on click outside. Pure HTML using `popovertarget`, no component needed.
clipboard-copy.md	ui-kit	Copy-to-clipboard button with "Copied!" feedback. Headless component — requires import.
letter-split.md	ui-kit	Splits dynamic text into one span per letter for individual character styling. Headless component — requires import.
popover-menu.md	ui-kit	Dropdown menu that opens on hover and closes when the mouse leaves. Headless component — requires import. For click-triggered popups, use `click-popover.md` instead (pure HTML).
scroll-carousel.md	ui-kit	Horizontal slider with CSS scroll snap. Headless component — requires import.
spring-button-hover.md	ui-kit	Bouncy hover on buttons (and button-like controls) using CSS `linear()` easing — no JavaScript or animation libraries.
sticky-header-scroll.md	ui-kit	A site header that stays `position: sticky` and morphs on scroll: padding compresses and a wavy bottom edge appears, driven by scroll-linked CSS (`animation-timeline: scroll()` + `clip-path: shape()`).
tabs.md	ui-kit	Switch between content panels with tab buttons. Pure CSS using radio inputs, no component needed.
toggle-switch.md	ui-kit	On/off toggle styled as a switch. Pure CSS using a checkbox input, no component needed.
tooltip.md	ui-kit	Hover tooltip showing extra info. Pure CSS using `::after` pseudo-element, no component needed.
word-split.md	ui-kit	Splits dynamic text into one span per word for individual word styling. Headless component — requires import.
a11y-patterns.md	a11y-validator	Common accessibility patterns and how to fix validation errors. Each section corresponds to an a11y-validator rule.
design-system.md	design-system-validator	The project uses a `DESIGN.md` file to define design tokens — colors, typography, spacing, rounded corners, and component specs. The validator enforces these tokens across all `.jay-html` pages.
font-fallback-patterns.md	design-system-validator	## Why metric-matched fallbacks matter
wix-media.md	wix-media	How to use images, video, documents, and audio from Wix Media Manager in jay-html templates.

About this document

This page is part of the Jay Stack Agent Kit — documentation generated from the framework source and written primarily for AI agents. The language and structure are optimized for machine consumption — expect precise, specification-style prose rather than narrative documentation. Learn more about the Agent Kit →