Skip to content
Closed
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
92 changes: 92 additions & 0 deletions site/app/[locale]/guide/authoring-plugins/content.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
## Overview

A Master CSS "plugin" is a normal npm package that exports a partial `Config` object. Consumers merge it via `extends`, so plugins compose in a deterministic order (later overrides earlier). There is no separate plugin runtime — everything is plain config.

## Anatomy of a plugin package

```ts name=src/index.ts
import type { Config } from '@master/css'

const plugin: Config = {
rules: {
'shadow-elevated': {
declarations: { 'box-shadow': '0 8px 24px rgba(0,0,0,.12)' }
}
},
variables: {
color: {
brand: { primary: '#4285f4', danger: '#e63946' }
}
},
components: {
card: 'bg:white shadow-elevated r:12 p:24'
}
}

export default plugin
```

```json name=package.json
{
"name": "master-css-preset-myteam",
"version": "0.1.0",
"type": "module",
"main": "./dist/index.cjs",
"module": "./dist/index.mjs",
"types": "./dist/index.d.ts",
"exports": {
".": {
"types": "./dist/index.d.ts",
"import": "./dist/index.mjs",
"require": "./dist/index.cjs"
}
},
"peerDependencies": {
"@master/css": "*"
}
}
```

`@master/css` is a **peer dependency** so the host project's version wins.

## Consuming the plugin

```ts name=master.css.ts
import myteam from 'master-css-preset-myteam'
import type { Config } from '@master/css'

export default {
extends: [myteam],
// overrides win over the plugin
variables: { color: { brand: { primary: '#0063f0' } } }
} satisfies Config
```

`extends` accepts an array — multiple plugins are applied left-to-right.

## What a plugin can ship

| Field | Use case |
|-------|----------|
| `rules` | Custom utility shorthands (`shadow-elevated`, `font-display`) |
| `utilities` | Static one-off declarations (`sr-only`, `not-sr-only`) |
| `variables` | Design tokens (colors, spacing, radii, font scales) |
| `modes` | Mode-scoped variable values (`light`, `dark`, custom) |
| `components` | Class compositions (`card`, `btn`, `btn-primary`) |
| `selectors` | Custom logical selector tokens |
| `at` | Custom at-rule tokens |
| `animations` | Reusable `@keyframes` |

Avoid bundling source files for these directly — emit compiled JS via your build of choice (`tsup`, `tsc`, `bun build`, `unbuild`).

## Conventions

- Name with the prefix `master-css-preset-` or `master-css-plugin-` so consumers can find it.
- Document required peer deps and the minimum `@master/css` version.
- Keep the public surface in one default export; named sub-exports for opt-in slices are fine.
- Don't import the runtime in the plugin — plugins ship config only.

## See also

- [Configuration reference](/guide/configuration)
- [`@master/css` core reference](/reference/core)
11 changes: 11 additions & 0 deletions site/app/[locale]/guide/authoring-plugins/metadata.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
import define from 'internal/utils/metadata'

const metadata = define({
title: 'Authoring a plugin / package',
description: 'How to extend Master CSS with a reusable config preset, utility set, or component library.',
category: 'Customization',
vercelOG: true,
fileURL: import.meta.url
})

export default metadata
15 changes: 15 additions & 0 deletions site/app/[locale]/guide/authoring-plugins/page.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
import createPage from '~/internal/factories/create-page'
import Layout from 'internal/layouts/doc'
import metadata from './metadata'
import dictionaries from '~/site/dictionaries'
import categories from '~/site/.categories/guide.json'

export const { Page, dynamic, revalidate, generateMetadata } = createPage({
metadata,
dictionaries,
categories,
content: import('./content.mdx'),
Layout,
})

export default Page
70 changes: 70 additions & 0 deletions site/app/[locale]/guide/grid-systems/content.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
## Overview

Master CSS doesn't ship a Bootstrap-style row/column scaffold — modern CSS Grid is expressive enough that a thin set of utilities does the job. This guide collects three common patterns.

## 12-column layout

```html
<div class="grid grid-cols:12 gap:24">
<header class="grid-col:span-12">…</header>
<main class="grid-col:span-8">…</main>
<aside class="grid-col:span-4">…</aside>
</div>
```

Stack on small screens by overriding `grid-col` at a breakpoint:

```html
<aside class="grid-col:span-4 grid-col:span-12@max-md">…</aside>
```

## Auto-fit responsive cards (no breakpoints)

This pattern fills the row with as many cards as fit, each at least `16rem` wide, then collapses naturally:

```html
<div class="grid grid-cols:repeat(auto-fit,minmax(16rem,1fr)) gap:16">
<article class="bg:white p:16 r:8">…</article>
<article class="bg:white p:16 r:8">…</article>
<article class="bg:white p:16 r:8">…</article>
</div>
```

## Named template areas

For app-shell style layouts, name regions and assign them with `grid-area:`:

```html
<div class="
grid
{grid-template-areas:'header header'|'sidebar main'|'footer footer'}
{grid-template-rows:auto|1fr|auto}
grid-template-cols:240|1fr
h:dvh
">
<header class="grid-area:header">…</header>
<aside class="grid-area:sidebar">…</aside>
<main class="grid-area:main">…</main>
<footer class="grid-area:footer">…</footer>
</div>
```

## When to reach for a fixed grid library

If your design assumes traditional 12-column gutters, breakpoint-specific column counts, or container queries against a parent grid, write the template once as a [component](/guide/components):

```ts name=master.css.ts
export default {
components: {
'grid-12': 'grid grid-cols:12 gap:24 mx:auto max-w:1280'
}
}
```

Now `<div class="grid-12">` expands to the full set of utilities anywhere it's used.

## See also

- [`grid-template-columns` reference](/reference/grid-template-columns)
- [`grid-area` reference](/reference/grid-area)
- [Components](/guide/components)
11 changes: 11 additions & 0 deletions site/app/[locale]/guide/grid-systems/metadata.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
import define from 'internal/utils/metadata'

const metadata = define({
title: 'Easy grid systems',
description: 'Building flexible page-layout grid systems with Master CSS utilities, no framework required.',
category: 'Recipes',
vercelOG: true,
fileURL: import.meta.url
})

export default metadata
15 changes: 15 additions & 0 deletions site/app/[locale]/guide/grid-systems/page.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
import createPage from '~/internal/factories/create-page'
import Layout from 'internal/layouts/doc'
import metadata from './metadata'
import dictionaries from '~/site/dictionaries'
import categories from '~/site/.categories/guide.json'

export const { Page, dynamic, revalidate, generateMetadata } = createPage({
metadata,
dictionaries,
categories,
content: import('./content.mdx'),
Layout,
})

export default Page
64 changes: 64 additions & 0 deletions site/app/[locale]/guide/installation/bun/content.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
## Overview

Bun ≥ 1.x runs JavaScript and bundles to a browser target. Master CSS works with Bun in two ways:

1. **Runtime injection** — let `@master/css-runtime` generate styles in the browser. Easiest setup, zero build configuration.
2. **Static extraction at build time** — call the `mcss` CLI in your `bun build` step to emit a single stylesheet. Best for production.

## Runtime injection

```bash
bun add @master/css @master/css-runtime
```

```ts name=src/index.ts
import { initCSSRuntime } from '@master/css-runtime'
import config from './master.css'

initCSSRuntime(config)
```

```ts name=src/master.css.ts
import type { Config } from '@master/css'

export default {} satisfies Config
```

```bash
bun --hot src/index.ts
```

## Static extraction

```bash
bun add -D @master/css @master/css.cli
```

```json name=package.json
{
"scripts": {
"build": "bun build ./src/index.tsx --outdir ./dist && mcss render \"dist/**/*.html\""
}
}
```

`mcss` walks the emitted HTML, collects every Master CSS class, and writes a single deduplicated stylesheet. Reference it with `<link rel=\"stylesheet\" href=\"./master.css\">` in your HTML entry.

## Configuration

```ts name=master.css.ts
import type { Config } from '@master/css'

export default {
variables: {
color: { primary: '#4285f4' }
}
} satisfies Config
```

Bun resolves the config natively — no `tsx` or `ts-node` needed.

## See also

- [Vite integration guide](/guide/installation/vite) for parallels in plugin form
- [`@master/css.cli` reference](/reference/cli)
11 changes: 11 additions & 0 deletions site/app/[locale]/guide/installation/bun/metadata.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
import define from 'internal/utils/metadata'

const metadata = define({
title: 'Set up Master CSS with Bun',
description: 'Guide to using Master CSS with the Bun runtime and bundler.',
category: 'Integrations',
vercelOG: true,
fileURL: import.meta.url
})

export default metadata
17 changes: 17 additions & 0 deletions site/app/[locale]/guide/installation/bun/page.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
import createPage from '~/internal/factories/create-page'
import Layout from 'internal/layouts/doc'
import metadata from './metadata'
import dictionaries from '~/site/dictionaries'
import categories from '~/site/.categories/guide.json'

export const { Page, dynamic, revalidate, generateMetadata } = createPage({
metadata,
dictionaries,
categories,
noTOC: true,
categoryLink: '/guide/installation/integrations',
content: import('./content.mdx'),
Layout,
})

export default Page
68 changes: 68 additions & 0 deletions site/app/[locale]/guide/installation/lit/content.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
## Overview

Lit components render inside a Shadow DOM by default, which means a globally injected stylesheet does **not** reach into them. There are two viable patterns:

1. **Use `:host` styles + the runtime** — let `@master/css-runtime` generate a single global stylesheet, but flatten components into the Light DOM (`createRenderRoot() { return this }`).
2. **Per-component stylesheets** — use the runtime in the page shell *and* re-attach an `adoptedStyleSheets` clone inside each component's shadow root.

## Light DOM (recommended for most apps)

```ts name=my-button.ts
import { LitElement, html } from 'lit'
import { customElement } from 'lit/decorators.js'

@customElement('my-button')
export class MyButton extends LitElement {
// opt out of Shadow DOM so global Master CSS classes apply
createRenderRoot() { return this }

render() {
return html`
<button class="bg:primary fg:white px:16 py:8 r:8 hover:bg:primary-70">
<slot></slot>
</button>
`
}
}
```

Bootstrap the runtime once at the app entry:

```ts name=index.ts
import { initCSSRuntime } from '@master/css-runtime'
import config from './master.css'
import './my-button'

initCSSRuntime(config)
```

## Shadow DOM with adoptedStyleSheets

```ts name=my-button.ts
import { LitElement, html } from 'lit'
import { customElement } from 'lit/decorators.js'
import { CSSRuntime } from '@master/css-runtime'
import config from './master.css'

const css = new CSSRuntime(config)
const sheet = new CSSStyleSheet()
sheet.replaceSync(css.text)

@customElement('my-button')
export class MyButton extends LitElement {
constructor() {
super()
this.shadowRoot && (this.shadowRoot.adoptedStyleSheets = [sheet])
}
render() {
return html`<button class="bg:primary fg:white px:16 py:8 r:8">…</button>`
}
}
```

This duplicates the stylesheet into every shadow root; use only when you need style isolation.

## See also

- [`@master/css-runtime` reference](/reference/runtime)
- [Lit docs — Styles](https://lit.dev/docs/components/styles/)
11 changes: 11 additions & 0 deletions site/app/[locale]/guide/installation/lit/metadata.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
import define from 'internal/utils/metadata'

const metadata = define({
title: 'Set up Master CSS in Lit',
description: 'Guide to using Master CSS inside Lit web components.',
category: 'Integrations',
vercelOG: true,
fileURL: import.meta.url
})

export default metadata
Loading
Loading