AI Context

---
name: intershapes
description: Full context for working with the Intershapes model — interface/shape/theme separation, naming conventions, file structure, and creation rules.
---

# Intershapes Model Context

## Mental Model

**Interface** — A data contract defining what a component consumes. TypeScript, GraphQL schema, JSON Schema — any machine-readable format works. Lives in `src/intershapes/{name}/interface.ts`.

**Shape** — A visual representation (Astro component) that conforms to an interface. Fixed HTML structure styled with `@scope` CSS. Lives in `src/intershapes/{name}/shapes/{ShapeName}.astro`.

**Theme** — An injectable set of colour tokens via `data-theme` attribute. Themes own colour; shapes own spacing, layout, padding, and radii. Defined in `src/intershapes/_tokens.css`.

**Primitive** — An atomic building block used across shapes and interfaces. Self-styled via `data-primitive` + `@scope`. Lives in `src/intershapes/_primitives/{Name}.astro`.

**Surfacing** — The act of selecting the right shape + theme for an interface in context. Can be done by a developer, rules engine, or AI.

## Namespace Imports

Shapes are imported as namespaces for clarity and autocomplete:

```typescript
import * as UserProfile from '../intershapes/profile/shapes';

// Usage:

```

`UserProfile.Horizontal` reads as "the Horizontal shape of the UserProfile interface."

Each interface has a `shapes/index.ts` that re-exports all shapes:

```typescript
export { default as Horizontal } from './Horizontal.astro';
export { default as Vertical } from './Vertical.astro';
export { default as Inline } from './Inline.astro';
```

## Theme Prop

Every shape accepts a `theme` prop:

```typescript
import type { ThemeName } from '../../_types';

interface Props {
  data: MyInterface;
  theme?: ThemeName;  // 'light' | 'dark' | 'brand' | 'elevated'
}

const { data, theme } = Astro.props;
```

The shape sets `data-theme={theme}` on its root element. No wrapper divs needed.

## Composition Modes

**AI-first (preferred):** Shapes can use other shapes when their interface includes nested data. Import the shape, pass the nested data, get a fully composed component.

```typescript
// Interface with nested data
interface Comment {
  body: string;
  timestamp: string;
  author: UserProfile;  // nested interface
}
```

```astro

import Profile from '../profile/shapes';


  
  
{data.body}

```

The AI passes the right data, the shape composes itself. This is where the power unlock happens — interfaces become the full specification, shapes become self-composing.

**Slots (explicit control):** For user-controlled composition, shapes can define named slots. The page chooses what to pass.

```astro

  

```

Use slots when the page needs control over which shape renders nested data. Use AI-first composition when the shape owns the decision.

## Naming Conventions

- **Interface directories**: lowercase, singular — `profile/`, `comment/`, `codepanel/`
- **Interface files**: always `interface.ts`
- **Shape files**: PascalCase — `Horizontal.astro`, `Block.astro`, `Fixed.astro`
- **data-shape attribute**: `"{entity}-{shapename}"` in lowercase — `profile-horizontal`, `codepanel-block`
- **data-primitive attribute**: lowercase — `avatar`, `badge`, `timestamp`, `colordot`, `numbercircle`, `backlink`

## Shape File Anatomy

```astro
---
import type { InterfaceName } from '../interface';
import type { ThemeName } from '../../_types';
import SomePrimitive from '../../_primitives/SomePrimitive.astro';

interface Props {
  data: InterfaceName;
  theme?: ThemeName;
}

const { data, theme } = Astro.props;
---


  
  
{data.field1}
  
{data.field2}



```

## Rules

### Token Rules
- Shapes read colours from CSS custom properties (`var(--surface)`, `var(--on-surface)`, etc.)
- No hardcoded hex/rgb colour values in shape CSS — always use `var(--token)`
- Themes own every colour; shapes own spacing, padding, layout, and radii
- New tokens go in both `_tokens.css` and `_tokens.json`

### CSS Rules
- All shape CSS uses `