AIditorEcosystemDocumentationDesign Log
GitHubGet Started
Project Structure
← Documentation
Designer28
Developer13
Plugin Developer20
DevOps6
Contracts5

Project Structure

Project Structure

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

Directory Layout

A jay-stack project follows this structure:

my-project/
├── .jay                         # Dev server configuration (optional)
├── package.json                 # Dependencies and scripts
├── tsconfig.json                # TypeScript config
├── public/                      # Static assets (images, fonts, etc.)
├── config/                      # Plugin configuration (generated by jay-stack setup)
│   ├── project.conf.yaml       # Project metadata (name, etc.)
│   └── <plugin-name>.yaml      # Plugin-specific config files
├── src/
│   ├── components/              # Headfull full-stack components (shared across pages)
│   │   └── site-header/
│   │       ├── site-header.ts
│   │       ├── site-header.jay-html
│   │       └── site-header.jay-contract
│   ├── pages/                   # Pages (directory-based routing)
│   │   ├── page.jay-html        # Homepage → /
│   │   ├── page.jay-contract    # Homepage contract (optional)
│   │   ├── products/
│   │   │   ├── page.jay-html    # Products list → /products
│   │   │   └── [slug]/
│   │   │       └── page.jay-html       # Product detail → /products/:slug
│   │   └── cart/
│   │       └── page.jay-html    # Cart → /cart
│   └── styles/
│       └── theme.css            # Global theme stylesheet
└── agent-kit/                   # Generated by jay-stack agent-kit
    ├── INSTRUCTIONS.md
    ├── materialized-contracts/  # Contracts and indexes
    └── references/              # Plugin reference data (product catalogs, schemas)
        └── <plugin-name>/       # Per-plugin discovery data

What You Create

As an agent building pages, you typically create:

  1. **src/pages/**/\*.jay-html** — Page templates (the main output)
  2. **src/pages/**/\*.jay-contract** — Page-level contracts (when the page has its own data)
  3. src/styles/*.css — Theme stylesheet (one per project, reused across pages)

You do not need to create: package.json, tsconfig.json, .jay, page.conf.yaml, src/init.ts, server actions, or services — these are set up by the project scaffolding, the Figma plugin, or provided by plugins.

Styling

Global Theme (src/styles/)

Each project has a theme CSS file in src/styles/ with CSS custom properties (design tokens):

:root {
  /* Colors */
  --bg-primary: #faf8f5;
  --bg-card: #ffffff;
  --text-primary: #2d2a26;
  --text-secondary: #6b665e;
  --accent: #c45c3e;
  --accent-hover: #d4704f;
  --border: #e8e4dd;

  /* Typography */
  --font-serif: 'Cormorant Garamond', Georgia, serif;
  --font-sans: 'DM Sans', -apple-system, sans-serif;

  /* Spacing & Layout */
  --radius-md: 10px;
  --radius-lg: 14px;
  --container-max: 1400px;
  --page-padding: 48px;
  --shadow-sm: 0 1px 3px rgba(0, 0, 0, 0.04);
  --shadow-md: 0 4px 12px rgba(0, 0, 0, 0.06);
}

The theme provides reusable CSS classes for common UI patterns:

  • Layout: .container, .container-narrow
  • Cards: .card, .card-elevated
  • Buttons: .btn, .btn-primary, .btn-secondary, .btn-ghost, .btn-sm, .btn-lg
  • Forms: .input, .select, .checkbox
  • Badges: .badge, .badge-accent, .badge-success, .badge-error
  • Typography: .page-title, .section-title, .label
  • Product components: .product-card, .product-card-image, .product-card-content, .product-card-price

Linking the Theme from Pages

Use a relative path from the page to the theme file:

<!-- From src/pages/page.jay-html (depth 1) -->
<link rel="stylesheet" href="../styles/theme.css" />

<!-- From src/pages/products/page.jay-html (depth 2) -->
<link rel="stylesheet" href="../../styles/theme.css" />

<!-- From src/pages/products/[slug]/page.jay-html (depth 3) -->
<link rel="stylesheet" href="../../../styles/theme.css" />

Page-Specific Styles

Add page-specific styles in <style> tags within the jay-html <head>:

<head>
  <link rel="stylesheet" href="../../styles/theme.css" />
  <style>
    .hero {
      padding: 80px 0;
      text-align: center;
    }
    .featured-grid {
      display: grid;
      grid-template-columns: repeat(3, 1fr);
      gap: 24px;
    }
  </style>
</head>

External Fonts

Import fonts in the theme CSS or via <link> in jay-html:

/* In theme.css */
@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap');

Responsive Design

Use media queries in the theme CSS or page-specific styles:

@media (max-width: 1024px) {
  .product-page-layout {
    grid-template-columns: 1fr;
  }
}
@media (max-width: 768px) {
  .products-grid {
    grid-template-columns: 1fr;
  }
}

Configuration Files

config/ (Plugin Configuration)

The config/ folder holds plugin configuration files, typically generated by jay-stack setup:

config/
├── project.conf.yaml       # Project name and metadata
└── wix-data.yaml           # Plugin-specific config (auto-generated by setup)

Plugins create their config files here during setup. The location is configured via configBase in the .jay file (defaults to ./config).

You generally don't need to create files here manually — plugins handle this via jay-stack setup. However, you may need to read these files to understand how a plugin is configured.

.jay (Dev Server Config)

Optional YAML file at project root:

devServer:
  portRange:
    - 3000
    - 3100
  pagesBase: ./src/pages
  componentsBase: ./src/components
  publicFolder: ./public
editorServer:
  portRange:
    - 3101
    - 3200

package.json (Scripts)

Standard scripts for jay-stack projects:

{
  "scripts": {
    "dev": "jay-stack-cli dev",
    "validate": "jay-stack-cli validate",
    "definitions": "jay-cli definitions src",
    "build": "npm run definitions"
  }
}

Common Page Patterns

Product List / Search Page

Uses a product search contract with filters, sorting, and pagination:

src/pages/products/
└── page.jay-html     # Search input, filters sidebar, product grid, load more

Product Detail Page (Dynamic Route)

Uses a product page contract with media gallery, options, and add-to-cart:

src/pages/products/[slug]/
└── page.jay-html      # Gallery, options, quantity, actions

Category Page

Uses a category contract with product grid:

src/pages/categories/[slug]/
└── page.jay-html      # Category hero, product grid, load more

Cart Page

Uses a cart contract with line items and checkout:

src/pages/cart/
└── page.jay-html      # Line items, quantity controls, summary, coupon, checkout

Homepage

Combines multiple headless components:

src/pages/
└── page.jay-html      # Hero, featured products, categories, etc.

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 →