@dominikcz/greg 0.9.27

package/docs/reference/steps.md

@@ -0,0 +1,200 @@
+---
+title: Steps
+---
+
+# Steps
+
+The `Steps` component renders a numbered, visually connected procedure list —
+ideal for installation guides, tutorials, and any sequential workflow.
+It is inspired by the Starlight `<Steps>` component.
+
+## Usage
+
+`Steps` supports two authoring styles:
+
+- Markdown tag usage in docs pages (`<Steps>...</Steps>`)
+- Direct component usage in `.svelte` files
+
+### Markdown tag usage
+
+Wrap a standard Markdown ordered list with `<Steps>`. No import is needed —
+the component is available automatically on every docs page.
+
+````md
+<Steps>
+
+1. **Install dependencies**
+   Run `npm install` in the project root.
+
+2. **Start the dev server**
+   ```bash
+   npm run dev
+   ```
+
+3. **Open the app**
+   Navigate to `http://localhost:5173` in your browser.
+
+</Steps>
+
+**Output:**
+````
+
+**Result:**
+
+<Steps>
+
+1. **Install dependencies**
+   Run `npm install` in the project root.
+
+2. **Start the dev server**
+   Run `npm run dev` in your terminal.
+
+3. **Open the app**
+   Navigate to `http://localhost:5173` in your browser.
+
+</Steps>
+
+### Direct component usage (`.svelte`)
+
+```svelte
+<script>
+   import Steps from '$components/Steps.svelte';
+</script>
+
+<Steps>
+   <ol>
+      <li><strong>Install dependencies</strong>Run <code>npm install</code>.</li>
+      <li><strong>Start dev server</strong>Run <code>npm run dev</code>.</li>
+      <li><strong>Open app</strong>Visit <code>http://localhost:5173</code>.</li>
+   </ol>
+</Steps>
+```
+
+**Output:**
+
+Equivalent numbered steps UI as in Markdown usage.
+
+## Step titles
+
+The first **bold** text (`**…**`) in each list item is automatically styled
+as a step title — slightly larger and heavier than the body text below it.
+
+````md
+<Steps>
+
+1. **Clone the repository**
+   `git clone https://github.com/your-org/your-repo.git`
+
+2. **Configure environment variables**
+   Copy `.env.example` to `.env` and fill in the required values.
+
+3. **Run the tests**
+   ```bash
+   npm test
+   ```
+
+</Steps>
+````
+
+<Steps>
+
+1. **Clone the repository**
+   `git clone https://github.com/your-org/your-repo.git`
+
+2. **Configure environment variables**
+   Copy `.env.example` to `.env` and fill in the required values.
+
+3. **Run the tests**
+   Run `npm test` to verify everything is set up correctly.
+
+</Steps>
+
+## Rich step content
+
+Each step can contain any block-level Markdown content — paragraphs, code
+fences, custom containers, images, and nested lists.
+
+````md
+<Steps>
+
+1. **Install the CLI**
+
+   ::: tip Requires Node.js 18+
+   Check your version with `node --version` before proceeding.
+   :::
+
+   ```bash
+   npm install -g my-cli
+   ```
+
+2. **Initialise a project**
+
+   ```bash
+   my-cli init my-project
+   cd my-project
+   ```
+
+3. **Deploy**
+
+   - Review `my-cli.config.js`
+   - Run `my-cli deploy`
+
+</Steps>
+````
+
+<Steps>
+
+1. **Install the CLI**
+
+   ::: tip Requires Node.js 18+
+   Check your version with `node --version` before proceeding.
+   :::
+
+   ```bash
+   npm install -g my-cli
+   ```
+
+2. **Initialise a project**
+
+   ```bash
+   my-cli init my-project
+   cd my-project
+   ```
+
+3. **Deploy**
+
+   - Review `my-cli.config.js`
+   - Run `my-cli deploy`
+
+</Steps>
+
+## Props
+
+```ts
+interface Props {
+  /** Step content — should be a Markdown ordered list. */
+  children?: Snippet;
+}
+```
+
+## CSS variables
+
+The component inherits Greg's accent and border colours automatically.
+Override them globally or per page with CSS:
+
+| Variable                   | Used for                                                 | Default value                                                                            |
+| -------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `--greg-accent`            | Number circle border and number colour                   | `#646cff` (or theme `--greg-accent` value)                                               |
+| `--greg-steps-guide-color` | Connector line between steps                             | `color-mix(in srgb, var(--greg-accent, #646cff) 42%, var(--greg-border-color, #e5e5ea))` |
+| `--greg-steps-guide-gap`   | Gap between each point and connector line                | `0.375rem`                                                                               |
+| `--greg-border-color`      | Fallback connector colour (used by guide-color fallback) | `#e5e5ea` (or theme `--greg-border-color` value)                                         |
+| `--greg-color`             | Step title text colour                                   | `inherit` (or theme `--greg-color` value)                                                |
+
+```css
+/* Example: teal accent for steps */
+.greg-steps {
+  --greg-accent: #0d9488;
+   --greg-steps-guide-color: #14b8a6;
+   --greg-steps-guide-gap: 0.375rem;
+}
+```

package/docs/reference/team-page.md

@@ -0,0 +1,189 @@
+---
+title: Team Page
+---
+
+# Team Page
+
+Greg ships Svelte team-page components.
+There are two ways to display team members: embedded in a doc page, or as a
+dedicated full-page layout.
+
+## Authoring styles
+
+Team components are available in both authoring contexts:
+
+- Markdown docs pages (`.md`) via component tags
+- Direct `.svelte` usage via imported components
+
+## Show team members inside a page
+
+Use `<TeamMembers>` anywhere in a Markdown page:
+
+::: code-group labels=[markdown, output]
+
+<<< @/snippets/reference/team-members-example.md
+
+<!--@include: @/snippets/reference/team-members-example.md-->
+
+:::
+
+### Direct component usage (`.svelte`)
+
+::: code-group labels=[svelte, output]
+
+```svelte
+<script>
+  import TeamMembers from '$components/TeamMembers.svelte';
+</script>
+
+<TeamMembers
+  size="medium"
+  members={[
+    {
+      avatar: 'https://avatars.githubusercontent.com/u/583231?s=96',
+      name: 'Monalisa Octocat',
+      title: 'Lead Developer',
+      links: [{ icon: 'github', link: 'https://github.com/octocat' }],
+    },
+    {
+      avatar: 'https://avatars.githubusercontent.com/u/480938?s=96',
+      name: 'Hubot',
+      title: 'Automation Bot',
+      links: [{ icon: 'github', link: 'https://github.com/hubot' }],
+    },
+  ]}
+/>
+```
+
+<!--@include: @/snippets/reference/team-members-medium-example.md-->
+
+:::
+
+### `<TeamMembers>` props
+
+```ts
+interface Props {
+  members: TeamMemberData[];
+  size?: 'small' | 'medium';   // default: 'medium'
+}
+```
+
+`small` is better for inline use inside regular doc pages; `medium` suits a
+dedicated team page.
+
+## Create a full team page
+
+Create a `.md` file (e.g. `docs/team.md`) and use the layout components:
+
+::: code-group labels=[markdown, output]
+
+<<< @/snippets/reference/team-full-example.md
+
+<!--@include: @/snippets/reference/team-full-example.md-->
+
+:::
+
+### Direct component usage (`.svelte`)
+
+::: code-group labels=[svelte, output]
+
+```svelte
+<script>
+  import TeamMembers from '$components/TeamMembers.svelte';
+</script>
+
+<h3>Our Team</h3>
+<p>The people behind Greg.</p>
+
+<h4>Core Team</h4>
+<TeamMembers
+  size="medium"
+  members={[
+    {
+      avatar: 'https://avatars.githubusercontent.com/u/10137?s=96',
+      name: 'Jane Doe',
+      title: 'Creator',
+      org: 'Acme Corp',
+      orgLink: 'https://acme.com',
+      desc: 'Open source enthusiast.',
+      links: [
+        { icon: 'github', link: 'https://github.com/janedoe' },
+        { icon: 'twitter', link: 'https://twitter.com/janedoe' },
+      ],
+      sponsor: 'https://github.com/sponsors/janedoe',
+    },
+    {
+      avatar: 'https://avatars.githubusercontent.com/u/583231?s=96',
+      name: 'Monalisa Octocat',
+      title: 'Lead Developer',
+      links: [{ icon: 'github', link: 'https://github.com/octocat' }],
+    },
+  ]}
+/>
+```
+
+<!--@include: @/snippets/reference/team-full-example.md-->
+
+:::
+
+## Component reference
+
+### `<TeamMember>` props
+
+```ts
+interface TeamMemberData {
+  avatar: string;         // image URL
+  name: string;
+  title?: string;
+  org?: string;
+  orgLink?: string;
+  desc?: string;          // HTML allowed
+  links?: SocialLinkItem[];
+  sponsor?: string;       // sponsor page URL
+  actionText?: string;    // button label, default 'Sponsor'
+}
+
+interface Props {
+  member: TeamMemberData;
+  size?: 'small' | 'medium';
+}
+```
+
+### `<TeamMembers>` props
+
+```ts
+interface Props {
+  members: TeamMemberData[];
+  size?: 'small' | 'medium';
+}
+```
+
+### `<TeamPage>`
+
+Wrapper that provides correct vertical spacing between sections. Accepts only
+`children` (Svelte snippet).
+
+### `<TeamPageTitle>`
+
+Section title block at the top of a `<TeamPage>`. Accepts `title` and `lead`
+props or their snippet variants.
+
+### `<TeamPageSection>`
+
+A section within a `<TeamPage>`. Accepts `title` / `lead` props and children.
+
+## Social icons
+
+The `icon` property of a `SocialLinkItem` can be:
+
+- A **string** name of a built-in icon. Supported values: `github`, `twitter`,
+  `x`, `linkedin`, `discord`, `facebook`, `instagram`, `mastodon`, `npm`,
+  `slack`, `youtube`.
+- An **object** `{ svg: string }` with custom SVG markup.
+
+```md
+links: [
+  { icon: 'github',  link: 'https://github.com/...' },
+  { icon: { svg: '<svg ...>...</svg>' }, link: 'https://...' },
+]
+```

package/docs/reference/theme.md

@@ -0,0 +1,150 @@
+---
+title: Theme & Styling
+---
+
+Greg ships a carefully crafted two-tone design system — a clean purple-accent
+**light** theme and a warm ember **dark** theme. Both are configured entirely via
+CSS custom properties.
+
+
+## Dark / light mode
+
+The user's OS preference (`prefers-color-scheme`) is detected on first load.
+Greg follows system theme by default and only persists a value in
+`localStorage` after a manual toggle.
+
+A light/dark toggle is always visible in the top-right header.
+
+When the user toggles theme manually, Greg switches to manual mode and stores:
+
+- `greg-theme-source = "manual"`
+- `greg-theme = "light" | "dark"`
+
+If system mode is active, those keys are removed and Greg follows
+`prefers-color-scheme`.
+
+## Theme-aware favicon and header logo
+
+Greg can switch favicon and header logo from app theme state (`data-theme`), not
+only from browser/system preference.
+
+If you need this behavior, use separate assets for each theme, for example:
+
+- `/favicon-light.svg`
+- `/favicon-dark.svg`
+
+Why two files: a single `favicon.svg` with only
+`@media (prefers-color-scheme: dark)` reacts to system theme. It does not always
+match an in-app manual toggle.
+
+
+## CSS variables
+
+All visual properties are controlled through CSS custom properties defined on
+`:root` (light) and `[data-theme="dark"]` (dark). Override them in your own
+`src/app.css` or inside a `<style>` block to customise the appearance.
+
+### Layout & colours
+
+| Variable                   | Light default | Description                     |
+| -------------------------- | ------------- | ------------------------------- |
+| `--greg-background`        | `#ffffff`     | Page background                 |
+| `--greg-main-background`   | `#ffffff`     | Content area background         |
+| `--greg-menu-background`   | `#f8f8f8`     | Sidebar background              |
+| `--greg-header-background` | `#ffffff`     | Top header background           |
+| `--greg-color`             | `#1a1a2e`     | Primary text colour             |
+| `--greg-border-color`      | `#e5e5ea`     | Divider and border colour       |
+| `--greg-accent`            | `#646cff`     | Primary brand / accent colour   |
+| `--greg-accent-light`      | `#ececf5`     | Soft accent (hover backgrounds) |
+| `--greg-header-height`     | `3.5rem`      | Top header height               |
+
+### Navigation
+
+| Variable                        | Light default | Description            |
+| ------------------------------- | ------------- | ---------------------- |
+| `--greg-menu-color`             | `#3d3d3d`     | Sidebar text colour    |
+| `--greg-menu-section-color`     | `#7a7a8c`     | Section header colour  |
+| `--greg-menu-active-background` | `#646cff`     | Active link background |
+| `--greg-menu-active-color`      | `#ffffff`     | Active link text       |
+| `--greg-menu-hover-background`  | `#ececf5`     | Hover background       |
+
+### Sidebar splitter
+
+| Variable                                    | Light default | Description                          |
+| ------------------------------------------- | ------------- | ------------------------------------ |
+| `--greg-splitter-handler-background`        | `#e5e5ea`     | Splitter handle background           |
+| `--greg-splitter-handler-color`             | `#7a7a8c`     | Splitter handle icon colour          |
+| `--greg-splitter-active-border`             | `#646cff`     | Splitter border colour on hover      |
+| `--greg-splitter-active-handler-background` | `#646cff`     | Splitter handle background on hover  |
+| `--greg-splitter-active-handler-color`      | `#f8f8f8`     | Splitter handle icon colour on hover |
+
+### Code blocks
+
+| Variable                   | Light default | Description               |
+| -------------------------- | ------------- | ------------------------- |
+| `--greg-code-background`   | `#f0f0f4`     | Inline code background    |
+| `--greg-code-color`        | `#1a1a2e`     | Inline code text colour   |
+| `--greg-code-inline-color` | `#e4004a`     | Inline code inline colour |
+
+### Status colours (containers & badges)
+
+| Variable                                                            | Description            |
+| ------------------------------------------------------------------- | ---------------------- |
+| `--greg-info-border`, `--greg-info-text`, `--greg-info-bg`          | Info container / badge |
+| `--greg-tip-border`, `--greg-tip-text`, `--greg-tip-bg`             | Tip container / badge  |
+| `--greg-warning-border`, `--greg-warning-text`, `--greg-warning-bg` | Warning                |
+| `--greg-danger-border`, `--greg-danger-text`, `--greg-danger-bg`    | Danger                 |
+
+### Outline / TOC
+
+| Variable                | Description                |
+| ----------------------- | -------------------------- |
+| `--greg-toc-background` | Outline panel background   |
+| `--greg-toc-color`      | Section label colour       |
+| `--greg-toc-link-color` | Link colour                |
+| `--greg-toc-link-hover` | Hover / active link colour |
+
+
+## Customising the accent colour
+
+```css
+/* src/app.css */
+:root {
+  --greg-accent:       #ff6f61;
+  --greg-accent-light: rgba(255, 111, 97, 0.12);
+  --greg-menu-active-background: #ff6f61;
+}
+```
+
+
+## Resizable sidebar
+
+The left navigation panel is **drag-to-resize**. A vertical splitter between the
+sidebar and content area accepts mouse drag events to set the sidebar width.
+
+The splitter includes a centered `EllipsisVertical` handle icon from
+`@lucide/svelte` to indicate draggability.
+
+Hover visuals are controlled by splitter-specific CSS variables
+(`--greg-splitter-active-border`,
+`--greg-splitter-active-handler-background`,
+`--greg-splitter-active-handler-color`), so you can style it independently of the
+global accent token.
+
+
+## Code highlighting theme
+
+Code blocks are highlighted by Shiki. Greg uses dual themes by default:
+`github-light` for light mode and `github-dark` for dark mode.
+
+To change themes, edit `svelte.config.js`:
+
+```js
+// svelte.config.js
+const shikiThemes = {
+  light: 'github-light',
+  dark: 'github-dark',
+};
+```
+
+Supported Shiki themes: see [shiki.style/themes](https://shiki.style/themes).