Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 4 additions & 5 deletions .changeset/modern-icon-library.md
Original file line number Diff line number Diff line change
@@ -1,19 +1,18 @@
---
"@xpecs/xote": minor
"xpecs": minor
"@prescriptive/xote": minor
---

Add a modern SVG icon library with an `Icon` component.

- **`@xpecs/xote`**: new `Icons` module — a curated outline icon set (50 glyphs)
- **`@prescriptive/xote`**: new `Icons` module — a curated outline icon set (50 glyphs)
in the Feather / Lucide visual language (24×24 grid, no fill, 2px round
strokes) — and an `Icon` element that renders a named glyph as an inline SVG.
Icons inherit the surrounding text color and optical size; pass `label` for a
meaningful icon (role=img + accessible name) or omit it to mark it decorative.
Sizes: `xs`, `sm`, `md`, `lg`, `xl`.
- **`@xpecs/xote`**: `Alert` now renders its `icon` as a glyph from the icon set
- **`@prescriptive/xote`**: `Alert` now renders its `icon` as a glyph from the icon set
(the prop takes an icon name) and shows a sensible per-variant default when none
is given.
- **`xpecs`**: the `icon` element spec now types `size` as an enum and maps its
- **`prescriptive`**: the `icon` element spec now types `size` as an enum and maps its
implementation to `Icon.res`, so the component is compiler-checked against the
contract.
12 changes: 6 additions & 6 deletions .changeset/reativa-components-package.md
Original file line number Diff line number Diff line change
@@ -1,18 +1,18 @@
---
"@xpecs/reativa": minor
"@prescriptive/reativa": minor
---

Add `@xpecs/reativa` — the ReasonML/OCaml (reativa + Melange) sibling of
`@xpecs/xote`, as its own package.
Add `@prescriptive/reativa` — the ReasonML/OCaml (reativa + Melange) sibling of
`@prescriptive/xote`, as its own package.

- Implements the same set `@xpecs/xote` covers — 22 elements, 8 components, and
- Implements the same set `@prescriptive/xote` covers — 22 elements, 8 components, and
7 blocks — in `.mlx` (JSX-for-OCaml) over `Reativa.View`, styled against
`@xpecs/tokens`, with the same behaviour and accessibility semantics as the
`@prescriptive/tokens`, with the same behaviour and accessibility semantics as the
Xote components.
- Enum prop types (`variant`, `size`, …) are generated from the specs' `## API`
contracts into `src/Contracts.ml` by `npm run contracts`, so the OCaml
compiler enforces that the implementation can't drift from the spec — the same
guarantee `@xpecs/xote` has.
guarantee `@prescriptive/xote` has.
- `src/Registry.mlx` renders one live example per spec and exports the JS surface
the website's **Reativa** preview consumes (`mount_example`, `example_ids`,
`built`). The website's example block now has two tab strips: one picks the
Expand Down
4 changes: 2 additions & 2 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -34,12 +34,12 @@ jobs:
# Clones reativa (pinned), compiles the .mlx examples inside its dune
# project, and bundles the output to website/src/reativa.bundle.js.
- name: Build reativa bundle (OCaml → esbuild)
run: npm run reativa --workspace xpecs-website
run: npm run reativa --workspace prescriptive-website

# Build the publishable packages (tokens → xote → skill).
- name: Build packages
run: npm run build:packages

# Build the website, which runs every conformance gate (npm run checks).
- name: Build website + run gates
run: npm run build --workspace xpecs-website
run: npm run build --workspace prescriptive-website
6 changes: 3 additions & 3 deletions .github/workflows/deploy-pages.yml
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ jobs:
node-version: 20
cache: npm

# Install the whole workspace so the website can resolve @xpecs/*.
# Install the whole workspace so the website can resolve @prescriptive/*.
- name: Install
run: npm ci

Expand All @@ -55,14 +55,14 @@ jobs:
# Clones reativa (pinned), compiles the .mlx examples inside its dune
# project, and bundles the output to website/src/reativa.bundle.js.
- name: Build reativa bundle (OCaml → esbuild)
run: npm run reativa --workspace xpecs-website
run: npm run reativa --workspace prescriptive-website

# Build the packages the website consumes (tokens → xote), then the site.
- name: Build packages
run: npm run build:packages

- name: Build website
run: npm run build --workspace xpecs-website
run: npm run build --workspace prescriptive-website
env:
# Project site path = repository name.
BASE_PATH: /${{ github.event.repository.name }}/
Expand Down
2 changes: 1 addition & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ follows [Semantic Versioning](https://semver.org/) and the format of
- `announcement-bar` — a slim, dismissible, page-width strip for one
timely message (a launch, promotion, or notice).
- **First block-level Xote components.** All seven new blocks ship with
`implementation:`-mapped components in `@xpecs/xote` (`PageHeader`,
`implementation:`-mapped components in `@prescriptive/xote` (`PageHeader`,
`StatGrid`, `LogoCloud`, `Steps`, `ContactSection`, `Newsletter`,
`AnnouncementBar`), so the conformance gate now checks blocks too. The
`steps` and `announcement-bar` enum props are compiler-enforced via the
Expand Down
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Contributing

Thanks for helping grow the Xpecs collection. The goal is a set of
Thanks for helping grow the Prescriptive collection. The goal is a set of
patterns that stay **consistent**, **stack-agnostic**, and **useful to both
humans and AI agents**. Consistency is the whole value, so the process is mostly
about keeping the shape uniform.
Expand Down
20 changes: 10 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Xpecs
# Prescriptive

A catalogue of **UX specs** — reusable, technology-agnostic definitions of UI
patterns, written to be a shared source of truth for **humans and AI agents**.
Expand All @@ -21,7 +21,7 @@ maps specs onto its own tokens, framework, and visual language.
Design systems and component libraries get re-invented on every project and
every stack. The visual skin and the framework change, but the underlying
_pattern_ — what a Button is, what a Navbar must do, what a Dashboard is for —
does not. Xpecs captures those stable patterns once, so they can be:
does not. Prescriptive captures those stable patterns once, so they can be:

- **Reused** across projects and stacks (React, Vue, SwiftUI, design tools, …).
- **Referenced** by AI agents as a source of truth when generating UI.
Expand Down Expand Up @@ -87,9 +87,9 @@ derived, consumable artifacts live under [`packages/`](packages/):

| Package | What it is |
| ------- | ---------- |
| **`xpecs`** (root) | The spec catalogue + design tokens — the source of truth every package below is generated from. |
| **[`@xpecs/tokens`](packages/tokens)** | The design tokens as ready-to-use artifacts: CSS custom properties, a **Tailwind v4 preset**, `[data-theme]`/`[data-mode]` overlays, and a typed JS export. |
| **[`@xpecs/xote`](packages/xote)** | Accessible [Xote](https://xote.dev)/ReScript components implementing the specs. Their prop types are generated from each spec's `## API`, so the compiler enforces they can't drift. Styled via `@xpecs/tokens`. |
| **`prescriptive`** (root) | The spec catalogue + design tokens — the source of truth every package below is generated from. |
| **[`@prescriptive/tokens`](packages/tokens)** | The design tokens as ready-to-use artifacts: CSS custom properties, a **Tailwind v4 preset**, `[data-theme]`/`[data-mode]` overlays, and a typed JS export. |
| **[`@prescriptive/xote`](packages/xote)** | Accessible [Xote](https://xote.dev)/ReScript components implementing the specs. Their prop types are generated from each spec's `## API`, so the compiler enforces they can't drift. Styled via `@prescriptive/tokens`. |
| **[`skill/`](skill/)** | An **Agent Skill** — the specs, traits, tokens, and responsive vocabulary compiled into a reference an AI coding agent loads to implement UI to the contracts. |

Each package is generated from the framework source, so nothing downstream can
Expand Down Expand Up @@ -129,7 +129,7 @@ Because the specs are structured, the build **checks** them (`npm run checks` in
## Repository layout

```
xpecs/ # root workspace = the `xpecs` spec + tokens source
prescriptive/ # root workspace = the `prescriptive` spec + tokens source
├── specs/ # the catalogue, one file per spec
│ ├── elements/ components/ blocks/ pages/ flows/
├── traits/ # shared interaction contracts
Expand All @@ -139,8 +139,8 @@ xpecs/ # root workspace = the `xpecs` spec + tokens sourc
├── templates/ # SPEC_TEMPLATE.md — the document pattern to copy
├── skill/ # the distributable Agent Skill
├── packages/
│ ├── tokens/ # @xpecs/tokens (CSS vars, Tailwind preset, JS)
│ └── xote/ # @xpecs/xote (Xote/ReScript components)
│ ├── tokens/ # @prescriptive/tokens (CSS vars, Tailwind preset, JS)
│ └── xote/ # @prescriptive/xote (Xote/ReScript components)
├── website/ # interactive catalogue (Vite + ReScript + Xote)
├── INDEX.md # generated registry of every spec
└── CHANGELOG.md
Expand All @@ -158,12 +158,12 @@ breakpoints — live in [`tokens/`](tokens/) in the standard
**[W3C Design Tokens (DTCG) format](https://www.w3.org/community/design-tokens/)**,
with ready-made themes in [`themes.json`](tokens/themes.json). Consume them as
CSS variables, a Tailwind preset, or a JS object via
[`@xpecs/tokens`](packages/tokens). See [`tokens/README.md`](tokens/README.md).
[`@prescriptive/tokens`](packages/tokens). See [`tokens/README.md`](tokens/README.md).

## Website

An interactive catalogue lives in [`website/`](website/): it lists every spec,
renders a **live example** of each (composed from `@xpecs/xote`), shows the API
renders a **live example** of each (composed from `@prescriptive/xote`), shows the API
contract and responsive behavior, and lets you retheme the whole site live from
the design tokens. Built with Vite, ReScript, [Xote](https://xote.dev), and
Tailwind CSS. See [`website/README.md`](website/README.md) to run it.
Expand Down
12 changes: 6 additions & 6 deletions RELEASING.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,15 +6,15 @@ and GitHub Actions. Four packages are published from this monorepo; the

| Package | Contents |
| ------- | -------- |
| `xpecs` | The spec catalogue + tokens (the repo root). |
| `@xpecs/tokens` | CSS variables, Tailwind preset, theme overlays, JS export. |
| `@xpecs/xote` | The Xote/ReScript component library. |
| `@xpecs/skill` | The Agent Skill (`SKILL.md` + compiled `reference/`). |
| `prescriptive` | The spec catalogue + tokens (the repo root). |
| `@prescriptive/tokens` | CSS variables, Tailwind preset, theme overlays, JS export. |
| `@prescriptive/xote` | The Xote/ReScript component library. |
| `@prescriptive/skill` | The Agent Skill (`SKILL.md` + compiled `reference/`). |

## One-time setup

1. **npm scope.** The publishing npm account must own the `@xpecs` scope
(create an org named `xpecs`, or publish under an account that owns it). The
1. **npm scope.** The publishing npm account must own the `@prescriptive` scope
(create an org named `prescriptive`, or publish under an account that owns it). The
scoped packages already declare `publishConfig.access = public`.
2. **`NPM_TOKEN` secret.** Add a repository secret `NPM_TOKEN` (Settings →
Secrets → Actions) containing an npm **Automation** token with publish
Expand Down
62 changes: 31 additions & 31 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

8 changes: 4 additions & 4 deletions package.json
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
{
"name": "xpecs",
"name": "prescriptive",
"version": "0.8.0",
"description": "A technology-agnostic collection of User Experience Specs: reusable definitions of UI patterns for humans and AI agents, spanning elements, components, blocks, pages, and flows.",
"workspaces": [
Expand All @@ -10,8 +10,8 @@
"scripts": {
"index": "node scripts/generate-index.mjs",
"skill": "node scripts/generate-skill.mjs",
"build:tokens": "npm run build --workspace @xpecs/tokens",
"build:packages": "npm run build --workspace @xpecs/tokens && npm run build --workspace @xpecs/xote && npm run build --workspace @xpecs/skill",
"build:tokens": "npm run build --workspace @prescriptive/tokens",
"build:packages": "npm run build --workspace @prescriptive/tokens && npm run build --workspace @prescriptive/xote && npm run build --workspace @prescriptive/skill",
"changeset": "changeset",
"version": "changeset version",
"release": "npm run build:packages && changeset publish"
Expand Down Expand Up @@ -42,7 +42,7 @@
],
"repository": {
"type": "git",
"url": "https://github.com/brnrdog/ux-archetypes"
"url": "https://github.com/brnrdog/prescriptive"
},
"devDependencies": {
"@changesets/cli": "^2.31.1"
Expand Down
12 changes: 6 additions & 6 deletions packages/reativa/README.md
Original file line number Diff line number Diff line change
@@ -1,19 +1,19 @@
# @xpecs/reativa
# @prescriptive/reativa

Accessible UI components for **[reativa](https://github.com/brnrdog/reativa)**
(OCaml + Melange) that implement the [Xpecs](https://github.com/brnrdog/ux-archetypes)
(OCaml + Melange) that implement the [Prescriptive](https://github.com/brnrdog/prescriptive)
contracts — the ReasonML/OCaml sibling of
[`@xpecs/xote`](../xote). Every element, component, and block is written in
[`@prescriptive/xote`](../xote). Every element, component, and block is written in
`.mlx` (JSX-for-OCaml) over `Reativa.View`, styled against
[`@xpecs/tokens`](../tokens), so a re-theme cascades through these exactly like
[`@prescriptive/tokens`](../tokens), so a re-theme cascades through these exactly like
it does through the Xote components.

There is no virtual DOM: `View.mount` builds real DOM nodes once and only the
reactive regions (driven by signals) update in place.

## What's implemented

The same set `@xpecs/xote` covers — 22 elements, 8 components, and 7 blocks:
The same set `@prescriptive/xote` covers — 22 elements, 8 components, and 7 blocks:

| Layer | Specs |
| ----- | ----- |
Expand Down Expand Up @@ -54,7 +54,7 @@ opam install dune melange mlx
Then:

```bash
npm run build --workspace @xpecs/reativa # contracts → melange → esbuild bundle
npm run build --workspace @prescriptive/reativa # contracts → melange → esbuild bundle
```

To move to a newer reativa, bump `REATIVA_REF` in `scripts/build.mjs`.
Expand Down
Loading
Loading