@ptbdynamic/plinth 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BDynamic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,259 @@
-# Temporary Holding Version
+# Plinth
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The design system of BDynamic's projects: design tokens, components as plain HTML and CSS, and
+thin Blade, Vue and React layers that print the same markup, documented and tested in Storybook.
+
+- **Tokens** are the source of truth: colour (light and dark), type, spacing, radii, layers,
+  breakpoints and motion. They are written once and built to CSS custom properties, a JS/TS
+  export and a Tailwind v4 theme file.
+- **Components are plain HTML and CSS.** Each one has a markup contract (its elements, classes,
+  states and ARIA) that every framework layer prints.
+- **Blade, Vue and React layers** print that markup and hold no styles of their own.
+- **Storybook** documents the plain HTML and tests it: accessibility and parity
+  between the story, Blade, Vue and React.
+- **Each project brings its brand through the tokens.** Plinth ships neutral defaults; a project
+  overrides the custom properties and never forks a component.
+
+## Layout
+
+```
+packages/
+  tokens/     the tokens in DTCG JSON (tokens/*.json), built with Style Dictionary to CSS custom
+              properties, a JS/TS export and a Tailwind theme
+  css/        one stylesheet per component, tokens only, mobile first; builds dist/plinth.css
+  vue/        Vue 3 components that print the markup contract
+  react/      React 19 components that print the same markup contract
+  blade/      Composer package: Blade components, a Filament plugin, and the built CSS
+storybook/    Storybook (HTML renderer): component stories, their docs pages, parity tests
+site/         Plinth's website, a Laravel app built with Plinth's components, and the guides in
+              site/docs (see site/README.md)
+```
+
+The npm workspaces are private. They are published together as one npm package and one Composer
+package (nothing is published yet):
+
+| Package              | Registry  | Holds                                                                                                      |
+| -------------------- | --------- | ---------------------------------------------------------------------------------------------------------- |
+| `@ptbdynamic/plinth` | npm       | `./tokens`, `./tokens.css`, `./css`, `./vue`, `./react` and `./tailwind.css`                               |
+| `ptbdynamic/plinth`  | Packagist | `<x-plinth::…>` Blade components, `PlinthPlugin` for Filament, the built CSS and fonts in `resources/dist` |
+
+Packagist reads the Composer package from the `composer.json` at the root of the repository, which
+points its autoload and Laravel provider at `packages/blade/`. `.gitattributes` marks everything
+else `export-ignore`, so a `composer require` downloads only `packages/blade/src`,
+`packages/blade/resources`, `composer.json`, `README.md` and `LICENSE` (and `CHANGELOG.md` once
+there is one). `packages/blade/composer.json` names the same package for the tests, the dev tools
+and the site's path repository.
+
+## Working on Plinth
+
+You need Node 22 (see `.nvmrc`), PHP 8.4 and Composer. `npm ci` also runs `composer install` in
+`packages/blade`.
+
+```bash
+npm ci
+npx playwright install chromium   # once, for the Storybook test runner
+
+npm run storybook                 # http://127.0.0.1:6006 (builds the tokens and CSS first)
+npm run build-storybook           # static build in storybook/storybook-static
+npm run check                     # everything CI runs (turbo run lint test build build-storybook)
+```
+
+[Turborepo](https://turborepo.com) runs each task in the order the packages depend on each other
+(`tokens` → `css` → `vue`, `react` and `blade` → `storybook` and `site`) and caches the results in `.turbo/`, so a
+second run with nothing changed is served from the cache. On a small machine, add
+`--concurrency=2`.
+
+`turbo.json` passes the `MISE_*`, `__MISE_*` and `LERD_*` variables through to tasks. Turborepo
+strips the environment by default, and without those variables lerd's `npm` shim (which runs npm
+through mise) finds itself on the `PATH` again and starts copies of itself until the machine runs
+out of memory.
+
+What the tests cover:
+
+- `packages/tokens`: Vitest on the build output. The three tiers are there, semantic colours are
+  built from primitives in both themes, text colours meet WCAG AA, and the CSS and Tailwind output
+  are right (Tailwind itself compiles the theme).
+- `packages/vue`: Vitest with Vue Test Utils.
+- `packages/react`: Vitest with Testing Library.
+- `packages/blade`: Pest with Testbench, including the Filament plugin (`composer test` there).
+- `storybook`: Vitest **parity tests** render every story's markup, the Blade component, the
+  Vue component and the React one, and compare them ignoring whitespace and attribute order. Then the Storybook
+  test runner opens every story in light and dark at 390, 768 and 1440 px and checks it with axe.
+
+Screenshot comparison is paused until the foundations settle
+([#9](https://github.com/ptbdynamic/plinth/issues/9)).
+
+## Tokens
+
+The tokens are in `packages/tokens/tokens/`, in three tiers ([ADR 1](docs/adr/0001-design-tokens-in-dtcg-built-with-style-dictionary.md)):
+
+| Tier      | File                                                   | Custom properties               | Used by                             |
+| --------- | ------------------------------------------------------ | ------------------------------- | ----------------------------------- |
+| Primitive | `primitives.json`                                      | `--plinth-ref-color-neutral-50` | semantic tokens only                |
+| Semantic  | `semantic.json`, `semantic.light.json`, `.dark.json`   | `--plinth-color-surface`        | components; projects override these |
+| Component | `component.json`, `component.light.json`, `.dark.json` | `--plinth-header-height`        | one component                       |
+
+The website has a page for each under **Foundations** (colour, typography, spacing and sizes,
+radii and elevation, layers and breakpoints, motion, the focus ring and component tokens), each
+showing the semantic tokens and the primitives they are built from. Its Markdown is in
+[`site/docs`](site/docs).
+
+## Installing Plinth in a Laravel project
+
+Once a version is on Packagist:
+
+```bash
+composer require ptbdynamic/plinth
+```
+
+Laravel discovers the service provider, and the components are available as `<x-plinth::badge>`.
+In a Filament panel, add the plugin and publish its CSS and fonts:
+
+```php
+use BDynamic\Plinth\Filament\PlinthPlugin;
+
+$panel->plugin(PlinthPlugin::make());
+```
+
+```bash
+php artisan filament:assets
+```
+
+Outside Filament, publish them with `php artisan vendor:publish --tag=plinth-assets` and link
+`vendor/plinth/fonts/index.css` and `vendor/plinth/plinth.css`, or import them in the app's Vite
+CSS from `vendor/ptbdynamic/plinth/packages/blade/resources/dist/`.
+
+## Using Plinth from a project while you work on it
+
+Link your local checkout instead of a published version. Build Plinth first
+(`npx turbo run build`) and rebuild when you change it.
+
+**Laravel**: add a Composer path repository to the project's `composer.json`:
+
+```json
+{
+  "repositories": [
+    { "type": "path", "url": "../plinth/packages/blade", "options": { "symlink": true } }
+  ],
+  "require": {
+    "ptbdynamic/plinth": "@dev"
+  }
+}
+```
+
+Then `composer update ptbdynamic/plinth`. In a Filament panel, add the plugin and publish its
+CSS:
+
+```php
+use BDynamic\Plinth\Filament\PlinthPlugin;
+
+$panel->plugin(PlinthPlugin::make());
+```
+
+```bash
+php artisan filament:assets
+```
+
+Outside Filament, publish the CSS and fonts with `php artisan vendor:publish --tag=plinth-assets`
+and link `vendor/plinth/fonts/index.css` and `vendor/plinth/plinth.css`. The Filament plugin
+registers both itself. Components are then available as `<x-plinth::badge>`.
+
+**Vue**: point npm at the checkout with a `file:` link:
+
+```json
+{
+  "dependencies": {
+    "@ptbdynamic/plinth": "file:../plinth"
+  }
+}
+```
+
+```ts
+import '@ptbdynamic/plinth/fonts.css'; // Geist and Geist Mono, the default typefaces
+import '@ptbdynamic/plinth/css';
+import { PlinthBadge } from '@ptbdynamic/plinth/vue';
+```
+
+**React** (an Inertia React app, or any React 19 app): the same `file:` link, then
+
+```tsx
+import '@ptbdynamic/plinth/fonts.css';
+import '@ptbdynamic/plinth/css';
+import { PlinthButton } from '@ptbdynamic/plinth/react';
+
+<PlinthButton variant="secondary" onClick={save}>
+  Save
+</PlinthButton>;
+```
+
+The React components take the Vue props by the same names. Vue's default slot is `children`, and
+its named slots are props that take a node (`icon`, `trailing`). Everything else, `className`
+and `ref` included, reaches the root element. They render the same on the server (Inertia's SSR)
+and in the browser.
+
+**Tailwind v4**: Plinth's CSS is in `@layer plinth`. Place that layer after Tailwind's reset and
+before its utilities, so a utility class can adjust a component without `!important`. Then import
+the theme file, so page code gets the tokens as utilities (`bg-surface`, `text-text-muted`, `p-4`,
+`rounded-md`):
+
+```css
+@layer theme, base, plinth, components, utilities;
+@import 'tailwindcss';
+@import '@ptbdynamic/plinth/css';
+@import '@ptbdynamic/plinth/tailwind.css';
+```
+
+**Your brand**: override the **semantic** tokens after Plinth's CSS, outside any layer (Plinth's
+own are inside `@layer plinth`, so yours win). Storybook's example brand,
+[`storybook/brands/example.css`](storybook/brands/example.css), is a complete example; switch to
+it with **Brand** in the toolbar.
+
+```css
+:root {
+  --plinth-color-accent: #0f766e;
+  --plinth-color-accent-hover: #115e59; /* override these two with accent */
+  --plinth-color-accent-active: #134e4a;
+  --plinth-radius-pill: 0.25rem;
+  --plinth-font-family-body: 'Your Font', system-ui, sans-serif;
+}
+[data-theme='dark'] {
+  --plinth-color-accent: #14b8a6;
+}
+```
+
+Dark mode follows the system, or `data-theme="dark"` / the `.dark` class on any ancestor;
+`data-theme="light"` forces light.
+
+## Releases
+
+Plinth has one version for npm and Packagist, and one tag, `v<version>`
+([ADR 4](docs/adr/0004-one-version-released-with-changesets.md)). What changed is in
+`CHANGELOG.md` (from the first release on), written by [Changesets](https://github.com/changesets/changesets):
+
+```bash
+npx changeset                    # in a pull request that changes a package: the bump and a line for the changelog
+npm run release:version          # on a branch: the next version, in every package and the changelog
+npm run release -- --dry-run     # what npm and Packagist would get, without tagging or publishing
+npm run release                  # on main, after the version pull request merges: tag and publish
+```
+
+The dry run (CI runs it on every pull request) also checks the Composer side: the root
+`composer.json` and `packages/blade/composer.json` name the same package with the same runtime
+requirements and provider and have no `version` (Packagist takes it from the tag),
+`composer validate --strict` passes on the root one, and `git archive` of the tag (or of `HEAD`
+before tagging) holds what the package needs and nothing else.
+
+### One-time steps for the owner
+
+Both registries are set up: Packagist publishes each tag through its GitHub hook, and
+`npm run release` publishes `@ptbdynamic/plinth` to npm under the `ptbdynamic` organisation
+(the person releasing runs `npm login` first, with a one-time code if their account uses
+two-factor authentication).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the rules every component follows.
+
+## Licence
+
+[MIT](LICENSE)

package/package.json

@@ -1,6 +1,101 @@
 {
   "name": "@ptbdynamic/plinth",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "The design system of BDynamic's projects: tokens, plain HTML and CSS components, and thin Blade, Vue and React layers.",
+  "license": "MIT",
+  "type": "module",
+  "packageManager": "npm@10.9.9",
+  "engines": {
+    "node": ">=22.18"
+  },
+  "workspaces": [
+    "packages/tokens",
+    "packages/css",
+    "packages/vue",
+    "packages/react",
+    "packages/blade",
+    "storybook",
+    "site"
+  ],
+  "exports": {
+    "./tokens": {
+      "types": "./packages/tokens/dist/index.d.ts",
+      "default": "./packages/tokens/dist/index.js"
+    },
+    "./tokens.css": "./packages/tokens/dist/tokens.css",
+    "./tailwind.css": "./packages/tokens/dist/tailwind-theme.css",
+    "./css": "./packages/css/dist/plinth.css",
+    "./fonts.css": "./packages/css/dist/fonts/index.css",
+    "./css/*": "./packages/css/dist/*",
+    "./vue": {
+      "types": "./packages/vue/dist/index.d.ts",
+      "default": "./packages/vue/dist/index.js"
+    },
+    "./react": {
+      "types": "./packages/react/dist/index.d.ts",
+      "default": "./packages/react/dist/index.js"
+    }
+  },
+  "files": [
+    "packages/tokens/dist",
+    "packages/css/dist",
+    "packages/vue/dist",
+    "packages/react/dist"
+  ],
+  "peerDependencies": {
+    "vue": "^3.5.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vue": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "check": "turbo run lint test build build-storybook",
+    "build": "turbo run build",
+    "lint": "eslint --cache --cache-location node_modules/.cache/eslint . && prettier --check --cache . && tsc -p scripts",
+    "format": "prettier --write --cache . && stylelint --fix \"packages/css/src/**/*.css\" && composer --working-dir=packages/blade format",
+    "test": "turbo run test",
+    "storybook": "turbo run storybook",
+    "build-storybook": "turbo run build-storybook",
+    "test:scripts": "vitest run --config scripts/vitest.config.ts --coverage",
+    "changeset": "changeset",
+    "release:version": "node scripts/release/version.ts",
+    "release": "node scripts/release/release.ts"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.31.1",
+    "@changesets/read": "^1.0.1",
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^22.20.5",
+    "@vitest/coverage-v8": "^5.0.5",
+    "eslint": "^10.13.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-storybook": "^10.6.2",
+    "eslint-plugin-vue": "^10.11.1",
+    "globals": "^17.13.0",
+    "prettier": "^3.9.10",
+    "stylelint": "^17.16.0",
+    "stylelint-config-recess-order": "^7.8.0",
+    "stylelint-config-standard": "^40.0.0",
+    "stylelint-order": "^8.1.2",
+    "turbo": "^2.11.9",
+    "typescript": "~6.0.3",
+    "typescript-eslint": "^8.71.2",
+    "vitest": "^5.0.5"
+  },
+  "overrides": {
+    "jest-runtime": "30.4.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/packages/css/dist/avatar.css

@@ -0,0 +1,122 @@
+/*
+ * Avatar: a person or an organisation, as an image, initials, or a person glyph.
+ *
+ * <span class="plinth-avatar" data-size="md" role="img" aria-label="Ana Lima, Online">
+ *   <img class="plinth-avatar-image" src="…" alt="">
+ *     or <span class="plinth-avatar-initials" aria-hidden="true">AL</span>
+ *     or <svg class="plinth-avatar-glyph" aria-hidden="true">…</svg>
+ *   <span class="plinth-avatar-status" data-tone="success" aria-hidden="true"></span>
+ * </span>
+ *
+ * The root carries the name (role="img", aria-label), with the status label after a comma. A
+ * decorative avatar, next to the name it shows, has aria-hidden="true" and no role or label.
+ * Image first, then initials (from the name, or given), then the glyph.
+ *
+ * Sizes (data-size): sm 24px, md 32px (default), lg 40px, xl 56px. Round by default
+ * (radius.pill), so a brand can square it. The status dot takes the badge's tones (data-tone:
+ * neutral, success, warning, danger) and a ring in the page colour; on another surface, set
+ * --plinth-avatar-ring on the container (a card: --plinth-color-surface-raised).
+ */
+
+@layer plinth {
+  .plinth-avatar {
+    --plinth-avatar-size: var(--plinth-size-avatar-md);
+    --plinth-avatar-surface: var(--plinth-color-surface-sunken);
+    --plinth-avatar-status: var(--plinth-color-text-subtle);
+    --plinth-avatar-ring: var(--plinth-color-surface);
+
+    position: relative;
+    display: inline-flex;
+    flex: none;
+    align-items: center;
+    justify-content: center;
+    inline-size: var(--plinth-avatar-size);
+    block-size: var(--plinth-avatar-size);
+    font-family: var(--plinth-font-family-body);
+    font-size: var(--plinth-font-size-xs);
+    font-weight: var(--plinth-font-weight-medium);
+    line-height: 1;
+    vertical-align: middle;
+    color: var(--plinth-color-text-muted);
+    user-select: none;
+    background-color: var(--plinth-avatar-surface);
+    border-radius: var(--plinth-radius-pill);
+  }
+
+  /*
+   * The hairline ring: over an image (positioned boxes paint after in-flow ones) and under the
+   * status dot (which comes later). A border, so forced-colours mode keeps the circle.
+   */
+  .plinth-avatar::before {
+    position: absolute;
+    inset: 0;
+    box-sizing: border-box;
+    pointer-events: none;
+    content: '';
+    border: var(--plinth-border-width-thin) solid var(--plinth-color-border);
+    border-radius: inherit;
+  }
+
+  .plinth-avatar[data-size='sm'] {
+    --plinth-avatar-size: var(--plinth-size-avatar-sm);
+  }
+
+  .plinth-avatar[data-size='lg'] {
+    --plinth-avatar-size: var(--plinth-size-avatar-lg);
+
+    font-size: var(--plinth-font-size-md);
+  }
+
+  .plinth-avatar[data-size='xl'] {
+    --plinth-avatar-size: var(--plinth-size-avatar-xl);
+
+    font-size: var(--plinth-font-size-xl);
+  }
+
+  .plinth-avatar-image {
+    inline-size: 100%;
+    block-size: 100%;
+    object-fit: cover;
+    border-radius: inherit;
+  }
+
+  .plinth-avatar-initials {
+    letter-spacing: var(--plinth-font-tracking-snug);
+  }
+
+  .plinth-avatar-glyph {
+    inline-size: 60%;
+    block-size: 60%;
+  }
+
+  .plinth-avatar-status {
+    position: absolute;
+    inset-block-end: 0;
+    inset-inline-end: 0;
+    inline-size: calc(var(--plinth-avatar-size) * 0.3);
+    block-size: calc(var(--plinth-avatar-size) * 0.3);
+    background-color: var(--plinth-avatar-status);
+
+    /* Stays round when a brand squares the avatar. */
+    border-radius: 50%;
+    box-shadow: 0 0 0 var(--plinth-border-width-thick) var(--plinth-avatar-ring);
+  }
+
+  .plinth-avatar-status[data-tone='success'] {
+    --plinth-avatar-status: var(--plinth-color-success);
+  }
+
+  .plinth-avatar-status[data-tone='warning'] {
+    --plinth-avatar-status: var(--plinth-color-warning);
+  }
+
+  .plinth-avatar-status[data-tone='danger'] {
+    --plinth-avatar-status: var(--plinth-color-danger);
+  }
+
+  @media (forced-colors: active) {
+    .plinth-avatar-status {
+      background-color: CanvasText;
+    }
+  }
+}

package/packages/css/dist/badge.css

@@ -0,0 +1,76 @@
+/*
+ * Badge: a short label with an optional dot and a tone.
+ *
+ * <span class="plinth-badge" data-tone="success">
+ *   <span class="plinth-badge-dot" aria-hidden="true"></span>
+ *   <span class="plinth-badge-label">Paid</span>
+ * </span>
+ *
+ * Tones: neutral (default, also when data-tone is missing), success, warning, danger.
+ * The label carries the meaning; the tone and the dot only reinforce it.
+ */
+
+@layer plinth {
+  .plinth-badge {
+    --plinth-badge-surface: var(--plinth-color-surface-sunken);
+    --plinth-badge-text: var(--plinth-color-text-muted);
+    --plinth-badge-accent: var(--plinth-color-text-muted);
+
+    display: inline-flex;
+    gap: var(--plinth-space-1);
+    align-items: center;
+    min-inline-size: 0;
+    max-inline-size: 100%;
+    padding-block: var(--plinth-space-0-5);
+    padding-inline: var(--plinth-space-2);
+    font-family: var(--plinth-font-family-body);
+    font-size: var(--plinth-font-size-xs);
+    font-weight: var(--plinth-font-weight-medium);
+    line-height: var(--plinth-font-leading-normal);
+    vertical-align: middle;
+    color: var(--plinth-badge-text);
+    white-space: nowrap;
+    background-color: var(--plinth-badge-surface);
+
+    /* Invisible normally; drawn by the system in forced-colours mode so the badge keeps its edge. */
+    border: 1px solid transparent;
+    border-radius: var(--plinth-radius-pill);
+  }
+
+  .plinth-badge[data-tone='success'] {
+    --plinth-badge-surface: var(--plinth-color-success-surface);
+    --plinth-badge-text: var(--plinth-color-success-text);
+    --plinth-badge-accent: var(--plinth-color-success);
+  }
+
+  .plinth-badge[data-tone='warning'] {
+    --plinth-badge-surface: var(--plinth-color-warning-surface);
+    --plinth-badge-text: var(--plinth-color-warning-text);
+    --plinth-badge-accent: var(--plinth-color-warning);
+  }
+
+  .plinth-badge[data-tone='danger'] {
+    --plinth-badge-surface: var(--plinth-color-danger-surface);
+    --plinth-badge-text: var(--plinth-color-danger-text);
+    --plinth-badge-accent: var(--plinth-color-danger);
+  }
+
+  .plinth-badge-dot {
+    flex: none;
+    inline-size: var(--plinth-space-2);
+    block-size: var(--plinth-space-2);
+    background-color: var(--plinth-badge-accent);
+    border-radius: var(--plinth-radius-pill);
+  }
+
+  .plinth-badge-label {
+    overflow: hidden;
+    text-overflow: ellipsis;
+  }
+
+  @media (forced-colors: active) {
+    .plinth-badge-dot {
+      background-color: currentcolor;
+    }
+  }
+}