From 99779fc48e837ee80dbd55549a4c6a6d5dc0282c Mon Sep 17 00:00:00 2001 From: Charan Date: Sun, 26 Jul 2026 18:41:40 +0530 Subject: [PATCH 1/2] docs: rewrite README for current monorepo state Replace outdated references to six archived themes (aurora, fern, cedar, mono, base, galley) with the three active scaffoldable themes (canopy, shadcn, galley). Add architecture diagram, feature table, CI/license badges, CLI options, full workspace table, and links to ARCHITECTURE, CONTRIBUTING, MIGRATION, and PUBLISHING docs. Document Node 22 requirement, local scaffold workflow (--from), and archive/ directory. Co-authored-by: Cursor --- README.md | 199 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 143 insertions(+), 56 deletions(-) diff --git a/README.md b/README.md index 45db464..b8f7d2d 100644 --- a/README.md +++ b/README.md @@ -2,87 +2,174 @@ # inkform-docs -**Open-source documentation framework for Next.js.** Beautiful docs, API -reference from OpenAPI, blog, and changelog — from a folder of Markdown. +**Open-source documentation framework for Next.js.** -`npx @inkform/cli@latest init my-docs` +Beautiful docs, native API reference from OpenAPI, blog, and changelog — from a folder of Markdown. + +
+ +[![CI](https://github.com/inkform-dev/framework/actions/workflows/ci.yml/badge.svg)](https://github.com/inkform-dev/framework/actions/workflows/ci.yml) +[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE) +[![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](./package.json) + +```bash +npx @inkform/cli@latest init my-docs +``` + +[Get started](#get-started) · [Themes](#themes) · [Features](#features) · [Develop](#develop-in-this-repo) · [Contributing](./CONTRIBUTING.md) --- -This is a monorepo. It contains: +## What is inkform-docs? -| Package | What it is | -| --- | --- | -| [`packages/framework`](./packages/framework) | `@inkform/framework` — the MDX + OpenAPI rendering engine | -| [`packages/cli`](./packages/cli) | `@inkform/cli` — `npx` scaffolder (pick a theme, get a project) | -| [`templates/aurora`](./templates/aurora) | classic dark docs theme | -| [`templates/fern`](./templates/fern) | clean, friendly green theme with Guides / API tabs | -| [`templates/cedar`](./templates/cedar) | warm, editorial theme | -| [`templates/mono`](./templates/mono) | monospace / brutalist theme | -| [`templates/base`](./templates/base) | minimal, unopinionated starter | -| [`templates/galley`](./templates/galley) | Inkform's own design system — warm paper + ink, one editorial red accent | -| [`examples/pokeapi-docs`](./examples/pokeapi-docs) | a full docs site for the PokéAPI | -| [`examples/markdown-docs`](./examples/markdown-docs) | a full docs site about Markdown | -| [`examples/inkform-docs`](./examples/inkform-docs) | the framework's own docs — dogfooded with the Galley theme | - -## Why inkform-docs - -- **Markdown in, polished docs out.** Write MDX, commit it, deploy. No CMS, no - database, no build service — your repo is the source of truth. -- **API reference is OpenAPI-first — and framework-native.** Point `docs.json` - at an OpenAPI spec and you get a searchable, paginated, "Try it"-enabled API - reference automatically. Rendered with the framework's own React - components — **zero Scalar/Vue dependency**, real per-operation pages - (SSG'd, not a client-side SPA embed), a real Try It console that makes - actual requests. Everything else is MDX. -- **Your docs are an MCP server.** Ship `/api/mcp` and every page — guides and - API operations alike — becomes callable by Claude, Cursor, or any MCP - client: `search`, `get_operation`, `list_operations`, `get_doc`. Self-hosted, - no external platform, no billing — it's just another Next.js route handler. -- **An AI ask-box grounded in your actual content**, not a hosted black box. - BYO model (Anthropic, OpenAI, or Google) and BYO API key; retrieval reuses - the same search the MCP server exposes, so the answers and the sources it - cites both trace back to real pages. -- **`/llms.txt` and `/llms-full.txt` out of the box** — the emerging - convention ([llmstxt.org](https://llmstxt.org)) for giving LLMs a plain-text - entry point into your content without crawling HTML. -- **Themes you actually choose between.** Five production themes that look - nothing alike, plus a minimal base — all driven by the same engine, so you can - switch with a token file. -- **Own your deployment.** It's a normal Next.js app. Ship it to Vercel, AWS - Amplify, a container, or under a path on a site you already run. -- **Genuinely open.** MIT, no telemetry, no required account, no lock-in. +**inkform-docs** is a self-hosted documentation framework. You write MDX, configure navigation in a single `docs.json` file, and deploy a normal Next.js app. No CMS, no database, no vendor lock-in. + +The engine (`@inkform/framework`) handles rendering, search, OpenAPI parsing, and optional AI/MCP integrations. Themes are thin Next.js apps that restyle the engine with CSS tokens. The CLI scaffolds a ready-to-deploy project in one command. + +``` +┌─────────────────────────────────────────────────────────┐ +│ Your content (MDX + docs.json + openapi.json) │ +└──────────────────────────┬──────────────────────────────┘ + │ +┌──────────────────────────▼──────────────────────────────┐ +│ @inkform/framework — MDX, OpenAPI, search, MCP, AI │ +└──────────────────────────┬──────────────────────────────┘ + │ +┌──────────────────────────▼──────────────────────────────┐ +│ Theme (Canopy / Shadcn / Galley) — tokens + layout │ +└──────────────────────────┬──────────────────────────────┘ + │ + Next.js 16 app → deploy anywhere +``` ## Get started +**Prerequisites:** [Node.js 22+](https://nodejs.org/) and npm. + ```bash npx @inkform/cli@latest init my-docs cd my-docs npm install -npm run dev +npm run dev # → http://localhost:3000 +``` + +The CLI prompts for a project folder and a theme, then writes a standalone Next.js project. Edit `content/docs/` to add pages, update `content/docs/docs.json` for navigation, and run `npm run build` when you're ready to deploy. + +**CLI options:** + +```bash +npx @inkform/cli@latest init my-docs --theme galley # skip theme prompt +npx @inkform/cli@latest init my-docs --openapi ./spec.yaml # wire up API reference +npx @inkform/cli@latest init my-docs -y # accept defaults ``` -The CLI asks for a project folder and a theme, then writes a standalone Next.js -project with a README that walks you through adding content and deploying. +The binary is also available as `inkform-docs` when installed globally. + +To embed the engine in an existing Next.js app or build a custom theme from scratch, see [`packages/framework`](./packages/framework) and [`packages/framework/ARCHITECTURE.md`](./packages/framework/ARCHITECTURE.md). + +## Features + +| | | +| --- | --- | +| **Markdown in, polished docs out** | Write MDX, commit it, deploy. Your repo is the source of truth — no CMS or build service required. | +| **Native OpenAPI API reference** | Point `docs.json` at a spec and get searchable, paginated, per-operation pages with a real Try It console. Rendered with the framework's own React components — zero Scalar/Vue dependency. | +| **MCP server** | Ship `/api/mcp` and every page becomes callable by Claude, Cursor, or any MCP client: `search`, `get_doc`, `list_operations`, `get_operation`. Self-hosted, no billing. | +| **AI ask-box** | BYO model (Anthropic, OpenAI, or Google) and API key. Answers are grounded in your actual content with cited sources. | +| **`/llms.txt` out of the box** | The [llms.txt](https://llmstxt.org) convention — a curated index and full-corpus export for LLMs and agentic tools. | +| **Full-text search** | [Pagefind](https://pagefind.app/) indexes your built HTML at deploy time. Fast, client-side, no server required. | +| **Blog & changelog** | Drop files in `content/blog/` or `content/changelog/` — routes and nav links appear automatically. | +| **Own your deployment** | A normal Next.js app. Ship to Vercel, AWS Amplify, a container, or a subpath on an existing site. | +| **Genuinely open** | MIT licensed. No telemetry, no required account, no lock-in. | + +## Themes + +Three production themes share one proven app structure. They differ only in design tokens, fonts, and brand assets — so switching themes is mostly a CSS file change. -To build your own theme or embed the engine in an existing app, see -[`packages/framework`](./packages/framework). +| Theme | Style | Best for | +| --- | --- | --- | +| [**Canopy**](./templates/canopy) *(default)* | Dark, vivid green accent, collapsible sidebar | Developer docs, API-first products | +| [**Shadcn**](./templates/shadcn) | Zinc monochrome, shadcn/ui aesthetic | Teams already on the shadcn design language | +| [**Galley**](./templates/galley) | Warm paper + ink, editorial red accent | Inkform's own design system — editorial, brand-forward sites | + +Legacy themes (Aurora, Fern, Cedar, Mono, Base, and an older Galley) are preserved in [`archive/templates/`](./archive/templates/) for reference but are not scaffoldable via the CLI. + +**Want to contribute a new theme?** See [Contributing a theme](./CONTRIBUTING.md#contributing-a-theme) — great designs can be added to the CLI's theme picker. + +## Monorepo + +This repository is an npm workspaces monorepo. Published packages ship to npm; everything else is private and used for development and demos. + +| Path | Package | Published | What it is | +| --- | --- | :---: | --- | +| [`packages/framework`](./packages/framework) | `@inkform/framework` | ✓ | The MDX + OpenAPI rendering engine | +| [`packages/cli`](./packages/cli) | `@inkform/cli` | ✓ | `npx` scaffolder (`inkform-docs` binary) | +| [`templates/canopy`](./templates/canopy) | `@inkform/theme-canopy` | | Canopy theme | +| [`templates/shadcn`](./templates/shadcn) | `@inkform/theme-shadcn` | | Shadcn theme | +| [`templates/galley`](./templates/galley) | `@inkform/theme-galley` | | Galley theme | +| [`examples/pokeapi-docs`](./examples/pokeapi-docs) | `@inkform/example-pokeapi` | | Full PokéAPI docs site (OpenAPI + e2e tests) | +| [`examples/markdown-docs`](./examples/markdown-docs) | `@inkform/example-markdown` | | Markdown/MDX feature reference | +| [`examples/inkform-docs`](./examples/inkform-docs) | `@inkform/example-inkform-docs` | | This framework's own docs (dogfooded) | ## Develop in this repo +**Prerequisites:** Node.js 22+, npm. + ```bash -npm install # installs all workspaces -npm run typecheck # typecheck every package -npm run dev --workspace=@inkform/example-pokeapi # run an example +git clone https://github.com/inkform-dev/framework.git +cd framework +npm install # installs all workspaces +npm run typecheck # typecheck every package +npm test # framework unit tests (Vitest) +npm run build # build all workspaces +npm run build:examples # build the three demo sites only ``` +**Run a workspace locally:** + +```bash +# Examples +npm run dev --workspace=@inkform/example-pokeapi +npm run dev --workspace=@inkform/example-inkform-docs +npm run dev --workspace=@inkform/example-markdown + +# Themes +npm run dev --workspace=@inkform/theme-canopy +npm run dev --workspace=@inkform/theme-shadcn +npm run dev --workspace=@inkform/theme-galley +``` + +**Scaffold from local templates** (useful when developing themes or the CLI): + +```bash +node packages/cli/bin/index.mjs init /tmp/test-docs --theme canopy --from templates -y +``` + +**End-to-end tests** (manual — not in CI, to avoid hammering the live PokéAPI): + +```bash +npm run test:e2e --workspace=@inkform/example-pokeapi +``` + +Changes to `packages/framework` are picked up immediately in themes and examples via the workspace link and `transpilePackages`. + +See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full contributor guide — PR process, theme requirements, and conventions. + +## Documentation + +| Doc | Description | +| --- | --- | +| [ARCHITECTURE.md](./packages/framework/ARCHITECTURE.md) | Engine API contract — read this before writing a theme or extending the framework | +| [CONTRIBUTING.md](./CONTRIBUTING.md) | How to contribute code, themes, and fixes | +| [CHANGELOG.md](./CHANGELOG.md) | Release history | +| [MIGRATION.md](./MIGRATION.md) | Upgrade guide (e.g. 0.3 → 0.4 native API renderer) | +| [PUBLISHING.md](./packages/framework/PUBLISHING.md) | Maintainer release process for npm packages | + ## Changelog -See [`CHANGELOG.md`](./CHANGELOG.md). Upgrading from an existing `docs.json` -and want to know what changed? See [`MIGRATION.md`](./MIGRATION.md). +See [`CHANGELOG.md`](./CHANGELOG.md). Upgrading from an existing `docs.json`? See [`MIGRATION.md`](./MIGRATION.md). ## License -MIT. +[MIT](./LICENSE) — Copyright (c) 2026 inkform. From 7c0d639370c251cc8f4aaa5c77226da49bdf4bfb Mon Sep 17 00:00:00 2001 From: Charan Date: Sun, 26 Jul 2026 18:42:01 +0530 Subject: [PATCH 2/2] docs: expand CONTRIBUTING with theme contribution guide Rewrite contributor docs for the consolidated three-theme structure. Add detailed theme contribution workflow: contract requirements, step-by-step setup, review criteria, and CLI registration. Document local scaffold testing (--from), CI gates, PR checklist, and engine/CLI contribution paths. Clarify archive/templates/ purpose and e2e exclusion rationale. Co-authored-by: Cursor --- CONTRIBUTING.md | 420 ++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 370 insertions(+), 50 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bf7838d..6a04d50 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,82 +1,402 @@ # Contributing to inkform-docs -Thanks for helping out! This is a workspace monorepo for an open-source -documentation framework. +Thank you for helping improve inkform-docs! This guide covers everything you +need to get started — from running the monorepo locally to shipping a new +documentation theme that lands in the CLI's theme picker. -## Layout +## Table of contents +- [Prerequisites](#prerequisites) +- [Repository layout](#repository-layout) +- [Development workflow](#development-workflow) +- [CI and quality gates](#ci-and-quality-gates) +- [How the pieces fit](#how-the-pieces-fit) +- [Contributing a theme](#contributing-a-theme) +- [Contributing engine features](#contributing-engine-features) +- [Contributing to the CLI](#contributing-to-the-cli) +- [Pull request process](#pull-request-process) +- [Conventions](#conventions) +- [Source mirror (maintainers)](#source-mirror-maintainers) + +--- + +## Prerequisites + +- **Node.js 22+** — required by the framework and CI (see root `engines`) +- **npm** — this monorepo uses npm workspaces (not pnpm or Turborepo) +- A GitHub account with access to fork and open PRs against + [`inkform-dev/framework`](https://github.com/inkform-dev/framework) + +```bash +git clone https://github.com/inkform-dev/framework.git +cd framework +npm install ``` -packages/framework @inkform/framework — the MDX + OpenAPI engine -packages/cli @inkform/cli — the `npx` scaffolder -templates/* the themes (aurora, fern, cedar, mono, base, galley) -examples/* full demo sites (pokeapi-docs, markdown-docs, inkform-docs) + +--- + +## Repository layout + +``` +packages/ + framework/ @inkform/framework — the MDX + OpenAPI engine (published) + cli/ @inkform/cli — the npx scaffolder (published) + +templates/ + canopy/ @inkform/theme-canopy — dark, green accent (default) + shadcn/ @inkform/theme-shadcn — zinc monochrome + galley/ @inkform/theme-galley — warm paper + ink + +examples/ + pokeapi-docs/ Full PokéAPI docs site + Playwright e2e tests + markdown-docs/ Markdown/MDX feature reference + inkform-docs/ This framework's own documentation (dogfooded) + +archive/templates/ Legacy themes (aurora, fern, cedar, mono, base, galley) + preserved for reference — not scaffoldable via CLI ``` -## Develop +Only `@inkform/framework` and `@inkform/cli` are published to npm. Themes and +examples are private workspace packages used for development and demos. + +--- + +## Development workflow ```bash -npm install # installs every workspace +npm install # install every workspace + run postinstall prune npm run typecheck # typecheck all packages -npm test # framework's Vitest unit tests -npm run build # next build across every theme + example +npm test # framework unit tests (Vitest) +npm run build # next build across every theme + example +npm run build:examples # build the three demo sites only +``` -# run a theme or example: -npm run dev --workspace=@inkform/theme-aurora +**Run a workspace locally:** + +```bash +# Examples npm run dev --workspace=@inkform/example-pokeapi +npm run dev --workspace=@inkform/example-inkform-docs +npm run dev --workspace=@inkform/example-markdown + +# Themes +npm run dev --workspace=@inkform/theme-canopy +npm run dev --workspace=@inkform/theme-shadcn +npm run dev --workspace=@inkform/theme-galley +``` + +Changes to `packages/framework` are picked up immediately in themes and +examples via the workspace link and `transpilePackages` — no publish step +needed during development. + +**Scaffold from local templates** (essential when developing themes or the CLI): + +```bash +node packages/cli/bin/index.mjs init /tmp/test-docs --theme canopy --from templates -y +cd /tmp/test-docs && npm install && npm run dev +``` + +Override the GitHub ref the CLI downloads from with `INKFORM_DOCS_REF=` +when testing against a fork or feature branch. + +**End-to-end tests** (manual — deliberately excluded from CI): -# real-browser e2e smoke test (builds + serves pokeapi-docs, drives it with -# a real Chromium; the one test that makes a real request talks to the -# live PokeAPI once, not in a loop): +```bash npm run test:e2e --workspace=@inkform/example-pokeapi ``` -Each theme/example is a standalone Next.js 16 app; the framework resolves via the -workspace link, so changes to `packages/framework` are picked up immediately -(thanks to `transpilePackages`). +The e2e suite makes one real request to the live PokéAPI per run. Fine for a +developer running it locally once, but not wired into CI to avoid hammering a +free, community-funded API on every push. + +--- + +## CI and quality gates + +`.github/workflows/ci.yml` runs on every PR and push to `main`: + +``` +lint → typecheck → test → build → npm audit --audit-level=high +``` -`.github/workflows/ci.yml` runs `lint` → `typecheck` → `test` → `build` → -`npm audit --audit-level=high` on every PR (whatever branch it targets — some -in-flight work here stacks a chain of PRs branch-to-branch before eventually -landing on `main`) and on every push to `main`. Same commands as above; -nothing CI does that you can't run locally first. +Run the same commands locally before opening a PR. Nothing CI does that you +can't reproduce on your machine. + +> **Note:** No workspace has a `lint` script yet — CI runs it with +> `--if-present` so it's a no-op today and will activate automatically once +> one is added. + +--- ## How the pieces fit -- The **framework** is headless logic + a themeable component kit. The public API - contract is documented in +``` +┌─────────────────────────────────────────────────────────┐ +│ Content (MDX + docs.json + openapi.json) │ +└──────────────────────────┬──────────────────────────────┘ + │ +┌──────────────────────────▼──────────────────────────────┐ +│ @inkform/framework — headless engine + component kit │ +│ (MDX, OpenAPI, search, MCP, AI, llms.txt) │ +└──────────────────────────┬──────────────────────────────┘ + │ +┌──────────────────────────▼──────────────────────────────┐ +│ Theme — Next.js app that imports the kit + theme.css │ +└──────────────────────────┬──────────────────────────────┘ + │ +┌──────────────────────────▼──────────────────────────────┐ +│ @inkform/cli — downloads a theme as a standalone app │ +└─────────────────────────────────────────────────────────┘ +``` + +- The **framework** is headless logic + a themeable component kit. The public + API contract lives in [`packages/framework/ARCHITECTURE.md`](./packages/framework/ARCHITECTURE.md). -- A **theme** is a full app that imports the kit and restyles it with a single - `app/theme.css` token file. Theme app code (routing, `lib/route.tsx`, the - `[[...slug]]` page, `components/`) is intentionally identical across themes — - the differences are tokens, fonts, and brand SVGs. -- The **CLI** downloads a theme as a standalone project. +- A **theme** is a full Next.js 16 app that imports the kit and restyles it + with a single `app/theme.css` token file. Routing, components, and page + structure are intentionally identical across themes — differences are tokens, + fonts, and brand SVGs. +- The **CLI** downloads a theme from GitHub (via giget) and scaffolds it as a + standalone project. + +--- + +## Contributing a theme + +New documentation site themes are one of the most valuable contributions you +can make. A well-designed theme that meets the contract below can be added to +the CLI's theme picker so every `npx @inkform/cli init` user can choose it. + +### What makes a good theme contribution + +- **Distinct visual identity** — it should look meaningfully different from + Canopy, Shadcn, and Galley. We want real variety, not a fourth green-accent + dark theme. +- **Polished defaults** — sample content, typography, spacing, and responsive + behavior should feel production-ready out of the box. +- **Token-driven styling** — all colors, radii, and density via `--fw-*` CSS + custom properties in `app/theme.css`. No hardcoded hex in components. +- **Accessible** — readable contrast, keyboard-navigable sidebar, sensible + focus states. Test light and dark modes if your theme supports both. +- **Complete contract** — ships every route and integration the contract + requires (see below). + +### The theme contract + +Every theme must satisfy the contract in +[`ARCHITECTURE.md` §12](./packages/framework/ARCHITECTURE.md#12-the-theme-contract). +In short, a theme is a standalone Next.js 16 app that: + +1. Has `content/docs/docs.json` + sample MDX + a sample `openapi.json`. +2. Imports `@inkform/framework/styles.css` once, then overrides `--fw-*` tokens + in `app/theme.css`. +3. Routes `/[[...slug]]` (docs), `/api-reference/[[...slug]]` (native OpenAPI + renderer), `/blog`, `/blog/[slug]`, and `/changelog`. +4. Builds a Pagefind search index via a `postbuild` script and mounts + ``, ``, and ``. +5. Ships `/api/ask` (AI ask-box, flag-gated), `/api/mcp` (MCP server), + `app/llms.txt` + `app/llms-full.txt`, `.env.example`, and a README with + content and deploy guides. +6. Sets `transpilePackages: ['@inkform/framework']` in `next.config.ts`. +7. Uses a unique workspace name `@inkform/theme-` and `"private": true`. + +**Themes differ by `theme.css` tokens, fonts, and brand assets — not by +re-implementing routing, the shell, or engine integrations.** + +### Step-by-step: adding a new theme + +1. **Copy an existing theme** as your starting point: + + ```bash + cp -r templates/canopy templates/ + ``` + + Canopy is the default and most complete reference. Use it unless you have a + specific reason to start from Shadcn or Galley. + +2. **Rename the package** in `templates//package.json`: -### Adding a theme + ```json + { + "name": "@inkform/theme-", + "description": " — one-line description" + } + ``` -1. Copy an existing theme dir (e.g. `templates/aurora`) to `templates/`. -2. Give it a unique `package.json` name (`@inkform/theme-`). -3. Restyle `app/theme.css` (tokens), `app/layout.tsx` (fonts), and `public/*.svg`. - Leave the routing/components alone. -4. Add it to the CLI's theme list in `packages/cli/src/scaffold.mjs`. -5. `npx tsc --noEmit` and `npx next build` must pass. +3. **Restyle** — this is where your design work lives: + - `app/theme.css` — override `--fw-*` design tokens (colors, radius, density) + - `app/layout.tsx` — font choices + - `public/logo.svg`, `public/favicon.svg`, `public/hero.svg` — brand assets + - `content/docs/docs.json` — update the sample site name and accent color -### Adding MDX components or engine features + Leave routing (`app/[[...slug]]/`, `lib/route.tsx`, `components/`) alone + unless you have a compelling UX reason and can justify the maintenance cost. -Implement in `packages/framework/src`, update `ARCHITECTURE.md`, and make sure -`npm run typecheck` passes from `packages/framework`. +4. **Verify locally:** + + ```bash + npm run typecheck --workspace=@inkform/theme- + npm run build --workspace=@inkform/theme- + npm run dev --workspace=@inkform/theme- + + # Scaffold test (from repo root): + node packages/cli/bin/index.mjs init /tmp/theme-test --theme --from templates -y + ``` + +5. **Register in the CLI** — add your theme to the `THEMES` array in + `packages/cli/src/scaffold.mjs`: + + ```js + { value: 'your-theme', label: 'Your Theme', hint: 'one-line description for the picker' }, + ``` + +6. **Write a theme README** at `templates//README.md` covering: + local dev, adding content, deploy to Vercel/Amplify, and any theme-specific + features (follow the Canopy README as a template). + +7. **Open a PR** with screenshots or a short screen recording showing your + theme in light and dark mode (if applicable), on desktop and mobile. + +### Theme review criteria + +Maintainers evaluate theme PRs on: + +| Criterion | What we look for | +| --- | --- | +| Visual quality | Distinct, polished, production-ready defaults | +| Contract compliance | All required routes, integrations, and build scripts present | +| Token hygiene | Styling via `--fw-*` tokens only; no hardcoded colors in components | +| Build health | `tsc --noEmit` and `next build` pass cleanly | +| Scaffold flow | `npx @inkform/cli init` with your theme produces a working project | +| Documentation | Theme README with content and deploy instructions | + +Themes that don't meet the bar can still be shared as community examples — we +just won't add them to the CLI picker until they're ready. + +--- + +## Contributing engine features + +Engine changes go in `packages/framework/src/`. + +1. Read [`ARCHITECTURE.md`](./packages/framework/ARCHITECTURE.md) first — + it is the stable API contract that themes, the CLI, and examples all build + against. +2. Implement in `packages/framework/src/`. +3. Add or update Vitest tests for non-trivial logic (`npm test`). +4. Update `ARCHITECTURE.md` if you change the public API (new exports, changed + behavior, new `docs.json` fields). +5. Verify downstream: `npm run typecheck` and `npm run build` from the repo root. + +If your change affects how themes wire up the engine (new route, new env var, +new component prop), update at least one theme as a reference implementation. + +--- + +## Contributing to the CLI + +The CLI lives in `packages/cli/`. Key files: + +| File | Purpose | +| --- | --- | +| `bin/index.mjs` | Entry point (`inkform-docs` binary) | +| `src/scaffold.mjs` | Scaffold logic, theme list, giget download | + +Test CLI changes locally: + +```bash +node packages/cli/bin/index.mjs init /tmp/cli-test --theme canopy --from templates -y +``` + +When adding a theme to the picker, only `scaffold.mjs` needs updating — the +CLI downloads templates from `github:inkform-dev/framework/templates/#main` +at scaffold time. + +--- + +## Pull request process + +1. **Fork** the repo and create a branch from `main`: + + ```bash + git checkout -b feat/my-contribution + ``` + +2. **Make your changes** following the conventions below. + +3. **Verify locally** before pushing: + + ```bash + npm run typecheck + npm test + npm run build + ``` + +4. **Open a PR** against `main` with: + - A clear title using [conventional commit](https://www.conventionalcommits.org/) style (`feat:`, `fix:`, `docs:`, `chore:`) + - A description of what changed and why + - Screenshots or recordings for visual changes (themes, UI components) + - A test plan — what you ran and what you verified + +5. **Address review feedback.** Maintainers may ask for changes before merging. + +### PR checklist + +- [ ] `npm run typecheck` passes +- [ ] `npm test` passes (if you touched `packages/framework`) +- [ ] `npm run build` passes +- [ ] `ARCHITECTURE.md` updated (if you changed the engine API) +- [ ] Theme README written (if you added a theme) +- [ ] CLI theme list updated (if you added a scaffoldable theme) +- [ ] No build artifacts committed (`.next/`, `*.tsbuildinfo`, `node_modules/`) + +--- + +## Conventions + +### Commits + +Use [conventional commit](https://www.conventionalcommits.org/) prefixes: + +``` +feat: add harbor theme with nautical tokens +fix: correct sidebar collapse on mobile +docs: update theme contract in ARCHITECTURE.md +chore: bump @inkform/framework to 0.4.1 +``` + +### TypeScript + +- Strict mode — no `any` that breaks the build +- ESM throughout (`"type": "module"` where applicable) + +### Styling + +- **Framework and theme components:** style only via `--fw-*` CSS custom + properties defined in `packages/framework/src/styles/tokens.css` and + overridden in each theme's `app/theme.css` +- **Icons:** [Lucide](https://lucide.dev/) with `strokeWidth={1.75}` (or + `~1.75`) +- **No hardcoded hex colors** in theme component files — use tokens + +### Files to never commit + +- `.next/`, `out/`, `.vercel/` +- `node_modules/` +- `*.tsbuildinfo` +- `.env.local` or any file containing secrets/API keys + +--- ## Source mirror (maintainers) This public repo is kept in sync with a private working monorepo via -`git subtree`. Merged PRs here are pulled back into the source, so contribute -normally — open a PR against this repo and it flows upstream. +`git subtree`. Merged PRs here are pulled back into the source repo, so +contribute normally — open a PR against this repo and it flows upstream. -## Conventions +--- -- Conventional-commit style messages (`feat:`, `fix:`, `docs:`, `chore:`). -- TypeScript strict; no `any` that breaks the build. -- Style only via `--fw-*` tokens + Lucide icons (`strokeWidth` ~1.75); no - hardcoded hex in theme components. -- Don't commit build artifacts (`.next`, `*.tsbuildinfo`) — they're gitignored. +## License -By contributing you agree your work is licensed under the repository's MIT license. +By contributing, you agree that your contributions are licensed under the +repository's [MIT License](./LICENSE).