Get Started

Learn the Intershapes methodology — how to build shapes, inject themes, and create interfaces that work for humans and machines.

01

The Model

Intershapes follows a five-step progression from need to rendered output:

1

Intent

You have a need: display user data, show notifications, render comments. The intent is the “what” — what information needs to appear and where.

2

Interfaces

Define a data contract describing what the component consumes — name, role, timestamp. Any machine-readable format works (TypeScript, GraphQL, JSON Schema); this site uses TypeScript. Stable, versioned, shareable.

3

Primitives

Atomic building blocks shared across shapes — Avatar, Badge, Timestamp. Self-styled via @scope, theme-aware. Defined once, reused everywhere.

4

Shapes

Structural HTML that conforms to an interface. Layout, spacing, composition — no colours. Replaceable — swap Horizontal for Vertical without breaking anything.

5

Themes

Injectable design tokens that control appearance. Colours only — injected at render time via CSS custom properties on a data-theme ancestor.

Once you have interfaces, shapes, and themes, surfacing is how they come together on a page — a five-layer resolution process that works from page intent inward to final themed output. Learn more about surfacing →

02

Built for Humans and Machines

Interfaces are machine-readable data contracts — readable by developers, parseable by tools, understandable by AI. Express them in whatever format your stack uses (TypeScript, GraphQL, JSON Schema). A shape creator can be:

  • A developer writing component files by hand
  • An AI generating markup from an interface definition
  • A design tool exporting structure from a visual editor

Because the interface is a contract, anything that can read it can build a shape. The methodology works whether you're hand-coding or generating.

03

Using Shapes

Shapes are imported as namespaces. UserProfile.Horizontal reads as "the Horizontal shape of the UserProfile interface."

Quick Start 
---
import * as UserProfile from '../intershapes/profile/shapes';

const user = { name: "Alan White", initials: "AW", role: "Admin" };
---

<UserProfile.Horizontal data={user} theme="dark" />

Rendered output

AW

Alan White

Admin
04

Theme is Flexible

Every shape receives a theme identifier via the theme prop. How you apply it is your choice.

This reference implementation uses CSS @scope with token variables. But the methodology is scoping-agnostic — use whatever isolation your stack provides. Tailwind utility classes, BEM modifiers, CSS Modules, CSS-in-JS, Shadow DOM — the shape doesn't care. It just receives a theme identifier and reads colours from tokens.

Available Themes

AW

Alan White

Admin

theme="light"

AW

Alan White

Admin

theme="dark"

AW

Alan White

Admin

theme="brand"

AW

Alan White

Admin

theme="elevated"

05

Building a Shape

Shapes define structure only. Colours come from theme tokens. Every shape accepts a theme prop and sets data-theme on its root element.

Shape anatomy — Horizontal.astro 
---
import type { UserProfile } from '../interface';
import type { ThemeName } from '../../_types';

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

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

<article data-shape="profile-horizontal" data-theme={theme}>
  <!-- structure only, no colours -->
  <h3>{data.name}</h3>
  <span>{data.role}</span>
</article>

<style is:global>
@scope ([data-shape="profile-horizontal"]) {
  :scope {
    /* layout owned by shape */
    display: flex;
    padding: 1rem;
    border-radius: 12px;

    /* colours from theme tokens */
    background: var(--surface);
    color: var(--on-surface);
  }
}
</style>

Key Principles

  • Shapes own structure — layout, padding, border-radius, composition
  • Themes own appearance — all colours through CSS variables
  • No hardcoded colours in shape CSS — always use var(--token)
06

Creating the Namespace

Create a shapes/index.ts file that re-exports all shapes. This enables namespace imports with autocomplete.

shapes/index.ts 
// shapes/index.ts
export { default as Horizontal } from './Horizontal.astro';
export { default as Vertical } from './Vertical.astro';
export { default as Inline } from './Inline.astro';

Now import * as UserProfile from '../shapes' gives you UserProfile.Horizontal, UserProfile.Vertical, etc. — with TypeScript autocomplete for all available shapes.

07

Custom Themes

The built-in themes (light, dark, brand, elevated) are starting points. Create your own by defining a [data-theme="custom"] block with the full token set:

Custom theme definition 
[data-theme="ocean"] {
  --surface: #0f172a;
  --on-surface: #e2e8f0;
  --on-surface-muted: #94a3b8;
  --on-surface-faint: #64748b;
  --border: #1e293b;
  --accent: #38bdf8;
  --avatar-bg: #1e293b;
  --avatar-text: #e2e8f0;
  --badge-bg: #1e293b;
  --badge-text: #94a3b8;
  /* ...status, code, dot tokens */
}

Then use it like any built-in theme: <UserProfile.Horizontal data=[object Object] theme="ocean" />. Every shape picks up your custom tokens automatically.

08

What Intershapes Doesn't Address

Intershapes is a render-time model for visual structure. It deliberately leaves these concerns to your framework and development practices:

State & Interactivity

Shapes are static HTML structure. State management, event handling, and reactivity are your framework's job — React, Vue, Svelte, or vanilla JS.

Responsive Page Layout

Layout primitives handle page-level responsive structure. Individual shapes own their internal layout, but page composition is outside shape scope.

Accessibility

Shapes provide correct semantic HTML and read from theme tokens for colour contrast. But keyboard navigation, screen reader support, and ARIA patterns are the developer's responsibility.

09

Contributing

Intershapes is a methodology, not a library. We're building a community around shared interfaces and multiple shape implementations.

New Interfaces

Add data contracts to the library. They become shared truth — versioned, stable, reusable across projects and organisations.

New Shapes

Build shapes for existing interfaces. Multiple implementations welcome — the same interface can have many visual representations.

Theme Approaches

Share how you implemented theming. Tailwind, BEM, CSS-in-JS — show others what works for your stack.

10

AI Context

This methodology is designed to be machine-readable. We give AI tools the same context we give human shape creators.

View the AI Context — the raw instructions we use for AI-assisted Intershapes development. Copy it into your AI tool to get the same deep understanding of the methodology.

View AI Context