@meddleware/dev 0.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +10 -0
- package/docs/.vitepress/config.ts +111 -0
- package/docs/.vitepress/env.d.ts +6 -0
- package/docs/.vitepress/theme/custom.css +63 -0
- package/docs/.vitepress/theme/index.ts +19 -0
- package/docs/design-system/components.md +111 -0
- package/docs/design-system/index.md +64 -0
- package/docs/design-system/tokens.md +136 -0
- package/docs/getting-started/index.md +52 -0
- package/docs/getting-started/local-dev.md +74 -0
- package/docs/getting-started/toolchain.md +83 -0
- package/docs/index.md +44 -0
- package/docs/sui/access-gate/gateway.md +159 -0
- package/docs/sui/access-gate/index.md +62 -0
- package/docs/sui/access-gate/integration.md +168 -0
- package/docs/sui/dao/index.md +154 -0
- package/docs/sui/environment.md +101 -0
- package/docs/sui/index.md +46 -0
- package/docs/sui/ptb-patterns.md +136 -0
- package/docs/sui/sealed-storage/index.md +49 -0
- package/docs/sui/sealed-storage/integration.md +125 -0
- package/docs/sui/sealed-storage/policies.md +81 -0
- package/docs/sui/walrus-storage/index.md +67 -0
- package/docs/sui/walrus-storage/integration.md +127 -0
- package/docs/sui/walrus-storage/relay-self-host.md +82 -0
- package/package.json +39 -0
- package/tsconfig.json +13 -0
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
# Changelog — @meddleware/dev
|
|
2
|
+
|
|
3
|
+
## 0.0.1
|
|
4
|
+
|
|
5
|
+
Initial release. Developer documentation site at `dev.meddleware.co.uk` covering:
|
|
6
|
+
|
|
7
|
+
- Getting started: toolchain prerequisites, local development
|
|
8
|
+
- Design system: consuming `@meddleware/design-tokens` and `@meddleware/ui`
|
|
9
|
+
- Sui development: environment setup, PTB patterns
|
|
10
|
+
- Per-service integration guides: Walrus Storage, Sealed Storage, Access Gate, DAO
|
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
import { defineConfig } from 'vitepress'
|
|
2
|
+
import { fileURLToPath } from 'node:url'
|
|
3
|
+
|
|
4
|
+
// Developer documentation for the Meddleware platform. Integration guides, design-system usage,
|
|
5
|
+
// self-host runbooks, and Sui development patterns. User-facing product docs live at docs.meddleware.co.uk.
|
|
6
|
+
// Output is pinned to the repo-root dist/ so the Dockerfile's `COPY --from=build /app/dist` works unchanged.
|
|
7
|
+
const outDir = fileURLToPath(new URL('../../dist', import.meta.url))
|
|
8
|
+
const srcDir = fileURLToPath(new URL('..', import.meta.url))
|
|
9
|
+
|
|
10
|
+
export default defineConfig({
|
|
11
|
+
title: 'Meddleware Dev',
|
|
12
|
+
description:
|
|
13
|
+
'Integration guides, design system usage, and Sui development patterns for the Meddleware platform.',
|
|
14
|
+
lang: 'en-GB',
|
|
15
|
+
srcDir,
|
|
16
|
+
outDir,
|
|
17
|
+
cleanUrls: true,
|
|
18
|
+
lastUpdated: false,
|
|
19
|
+
appearance: 'dark',
|
|
20
|
+
head: [['meta', { name: 'theme-color', content: '#5e1622' }]],
|
|
21
|
+
|
|
22
|
+
themeConfig: {
|
|
23
|
+
search: { provider: 'local' },
|
|
24
|
+
|
|
25
|
+
nav: [
|
|
26
|
+
{ text: 'Getting started', link: '/getting-started/' },
|
|
27
|
+
{ text: 'Design system', link: '/design-system/' },
|
|
28
|
+
{ text: 'Sui', link: '/sui/' },
|
|
29
|
+
{ text: 'API reference →', link: 'https://docs.meddleware.co.uk/blockchain/sui/' },
|
|
30
|
+
// TODO white-label: { text: 'Operator guides', link: '/operator/' }
|
|
31
|
+
],
|
|
32
|
+
|
|
33
|
+
sidebar: {
|
|
34
|
+
'/getting-started/': [
|
|
35
|
+
{
|
|
36
|
+
text: 'Getting started',
|
|
37
|
+
items: [
|
|
38
|
+
{ text: 'Overview', link: '/getting-started/' },
|
|
39
|
+
{ text: 'Toolchain', link: '/getting-started/toolchain' },
|
|
40
|
+
{ text: 'Local development', link: '/getting-started/local-dev' },
|
|
41
|
+
],
|
|
42
|
+
},
|
|
43
|
+
],
|
|
44
|
+
'/design-system/': [
|
|
45
|
+
{
|
|
46
|
+
text: 'Design system',
|
|
47
|
+
items: [
|
|
48
|
+
{ text: 'Overview', link: '/design-system/' },
|
|
49
|
+
{ text: 'Design tokens', link: '/design-system/tokens' },
|
|
50
|
+
{ text: 'Components', link: '/design-system/components' },
|
|
51
|
+
],
|
|
52
|
+
},
|
|
53
|
+
],
|
|
54
|
+
'/sui/': [
|
|
55
|
+
{
|
|
56
|
+
text: 'Sui',
|
|
57
|
+
items: [
|
|
58
|
+
{ text: 'Overview', link: '/sui/' },
|
|
59
|
+
{ text: 'Environment setup', link: '/sui/environment' },
|
|
60
|
+
{ text: 'PTB patterns', link: '/sui/ptb-patterns' },
|
|
61
|
+
],
|
|
62
|
+
},
|
|
63
|
+
{
|
|
64
|
+
text: 'Walrus Storage',
|
|
65
|
+
collapsed: true,
|
|
66
|
+
items: [
|
|
67
|
+
{ text: 'SDK setup', link: '/sui/walrus-storage/' },
|
|
68
|
+
{ text: 'Integration guide', link: '/sui/walrus-storage/integration' },
|
|
69
|
+
{ text: 'Self-host a relay', link: '/sui/walrus-storage/relay-self-host' },
|
|
70
|
+
// TODO white-label: { text: 'White-label operator guide', link: '/sui/walrus-storage/operator' }
|
|
71
|
+
],
|
|
72
|
+
},
|
|
73
|
+
{
|
|
74
|
+
text: 'Sealed Storage',
|
|
75
|
+
collapsed: true,
|
|
76
|
+
items: [
|
|
77
|
+
{ text: 'SDK setup', link: '/sui/sealed-storage/' },
|
|
78
|
+
{ text: 'Integration guide', link: '/sui/sealed-storage/integration' },
|
|
79
|
+
{ text: 'Writing policies', link: '/sui/sealed-storage/policies' },
|
|
80
|
+
// TODO white-label: { text: 'White-label operator guide', link: '/sui/sealed-storage/operator' }
|
|
81
|
+
],
|
|
82
|
+
},
|
|
83
|
+
{
|
|
84
|
+
text: 'Access Gate',
|
|
85
|
+
collapsed: true,
|
|
86
|
+
items: [
|
|
87
|
+
{ text: 'SDK setup', link: '/sui/access-gate/' },
|
|
88
|
+
{ text: 'Integration guide', link: '/sui/access-gate/integration' },
|
|
89
|
+
{ text: 'Deploy the gateway', link: '/sui/access-gate/gateway' },
|
|
90
|
+
// TODO white-label: { text: 'White-label operator guide', link: '/sui/access-gate/operator' }
|
|
91
|
+
],
|
|
92
|
+
},
|
|
93
|
+
{
|
|
94
|
+
text: 'DAO',
|
|
95
|
+
collapsed: true,
|
|
96
|
+
items: [
|
|
97
|
+
{ text: 'Governance patterns', link: '/sui/dao/' },
|
|
98
|
+
// TODO white-label: { text: 'White-label operator guide', link: '/sui/dao/operator' }
|
|
99
|
+
],
|
|
100
|
+
},
|
|
101
|
+
],
|
|
102
|
+
},
|
|
103
|
+
|
|
104
|
+
socialLinks: [{ icon: 'github', link: 'https://github.com/meddleware-org' }],
|
|
105
|
+
|
|
106
|
+
footer: {
|
|
107
|
+
message: 'Developer documentation for the Meddleware platform.',
|
|
108
|
+
copyright: 'Meddleware · 0BSD',
|
|
109
|
+
},
|
|
110
|
+
},
|
|
111
|
+
})
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
/*
|
|
2
|
+
* Meddleware brand overrides for the VitePress default theme.
|
|
3
|
+
* Brand = the functional primaries from @meddleware/design-tokens (red accent + blue), so the
|
|
4
|
+
* dev docs track the apps. No gold/purple (design philosophy: primary/rainbow accents as human
|
|
5
|
+
* universals, not royalty/priesthood signalling).
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
:root {
|
|
9
|
+
/* Brand = primary red (mirrors --accent in the apps). */
|
|
10
|
+
--vp-c-brand-1: var(--mw-red-500);
|
|
11
|
+
--vp-c-brand-2: var(--mw-red-300);
|
|
12
|
+
--vp-c-brand-3: var(--mw-red-300);
|
|
13
|
+
--vp-c-brand-soft: color-mix(in srgb, var(--mw-red-500) 14%, transparent);
|
|
14
|
+
|
|
15
|
+
/* Home hero: red → blue wash, warm (orange) glow — no gold. */
|
|
16
|
+
--vp-home-hero-name-color: transparent;
|
|
17
|
+
--vp-home-hero-name-background: linear-gradient(
|
|
18
|
+
120deg,
|
|
19
|
+
var(--mw-red-500),
|
|
20
|
+
var(--mw-blue-500)
|
|
21
|
+
);
|
|
22
|
+
--vp-home-hero-image-background-image: linear-gradient(
|
|
23
|
+
120deg,
|
|
24
|
+
var(--mw-red-300),
|
|
25
|
+
var(--mw-orange-500)
|
|
26
|
+
);
|
|
27
|
+
--vp-home-hero-image-filter: blur(44px);
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
.dark {
|
|
31
|
+
/* Dark mode: lightened red for legibility (mirrors --accent dark stop in tokens). */
|
|
32
|
+
--vp-c-brand-1: var(--mw-red-300);
|
|
33
|
+
--vp-c-brand-2: var(--mw-red-300);
|
|
34
|
+
--vp-c-brand-3: var(--mw-red-500);
|
|
35
|
+
--vp-c-brand-soft: color-mix(in srgb, var(--mw-red-500) 30%, transparent);
|
|
36
|
+
|
|
37
|
+
--vp-home-hero-name-background: linear-gradient(
|
|
38
|
+
120deg,
|
|
39
|
+
var(--mw-red-300),
|
|
40
|
+
var(--mw-blue-300)
|
|
41
|
+
);
|
|
42
|
+
--vp-home-hero-image-background-image: linear-gradient(
|
|
43
|
+
120deg,
|
|
44
|
+
var(--mw-red-500),
|
|
45
|
+
var(--mw-orange-500)
|
|
46
|
+
);
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/* "tip" custom blocks use the info (blue) role — functional, not gold. */
|
|
50
|
+
.vp-doc .custom-block.tip {
|
|
51
|
+
border-color: var(--mw-blue-500);
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
/* Encouraging prompt rendered below the hero tagline on the home page (home-hero-actions-after slot). */
|
|
55
|
+
.home-explore-prompt {
|
|
56
|
+
margin: 0 auto 2rem;
|
|
57
|
+
max-width: 480px;
|
|
58
|
+
text-align: center;
|
|
59
|
+
font-size: 1rem;
|
|
60
|
+
font-weight: 500;
|
|
61
|
+
color: var(--vp-c-brand-1);
|
|
62
|
+
line-height: 1.5;
|
|
63
|
+
}
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
// Dev theme = VitePress default theme + Meddleware brand overrides.
|
|
2
|
+
// The design-token CSS is imported so the palette stays in lockstep with the apps; custom.css
|
|
3
|
+
// maps VitePress's --vp-c-brand-* onto the functional primary ramps from design-tokens.
|
|
4
|
+
import { h } from 'vue'
|
|
5
|
+
import DefaultTheme from 'vitepress/theme'
|
|
6
|
+
import type { Theme } from 'vitepress'
|
|
7
|
+
import '@meddleware/design-tokens/tokens.css'
|
|
8
|
+
import './custom.css'
|
|
9
|
+
|
|
10
|
+
const theme: Theme = {
|
|
11
|
+
extends: DefaultTheme,
|
|
12
|
+
Layout: () =>
|
|
13
|
+
h(DefaultTheme.Layout, null, {
|
|
14
|
+
'home-hero-actions-after': () =>
|
|
15
|
+
h('p', { class: 'home-explore-prompt' }, 'Choose a topic above to start building.'),
|
|
16
|
+
}),
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
export default theme
|
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
# Components
|
|
2
|
+
|
|
3
|
+
`@meddleware/ui` exports a Vue 3 component library. All components are styled exclusively via CSS custom properties from `@meddleware/design-tokens` — no hardcoded values.
|
|
4
|
+
|
|
5
|
+
## Installation
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install @meddleware/ui @meddleware/design-tokens
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
`vue ^3.5.0` is a peer dependency — supply your own.
|
|
12
|
+
|
|
13
|
+
## Layout shell
|
|
14
|
+
|
|
15
|
+
The three shell components share an identical prop API:
|
|
16
|
+
|
|
17
|
+
```vue
|
|
18
|
+
<AppHeader variant="dark" />
|
|
19
|
+
<AppSidebar variant="light" />
|
|
20
|
+
<AppFooter variant="transparent" :docs-url="DOCS_URL" :dev-url="DEV_URL" />
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
| Prop | Type | Default | Description |
|
|
24
|
+
| --- | --- | --- | --- |
|
|
25
|
+
| `variant` | `'dark' \| 'light' \| 'transparent'` | `'transparent'` | Colour scheme for the shell component (theme-independent — `'dark'` renders correctly on a light page) |
|
|
26
|
+
| `colors` | `PanelColors` | — | Per-instance override of any `--mw-panel-*` token |
|
|
27
|
+
| `docsUrl` | `string` | — | `AppFooter` only — "Documentation" link href |
|
|
28
|
+
| `devUrl` | `string` | — | `AppFooter` only — "Developer docs" link href |
|
|
29
|
+
|
|
30
|
+
### Slots
|
|
31
|
+
|
|
32
|
+
`AppHeader` and `AppSidebar` expose named slots for custom content:
|
|
33
|
+
|
|
34
|
+
```vue
|
|
35
|
+
<AppHeader variant="dark">
|
|
36
|
+
<template #logo><!-- custom logo --></template>
|
|
37
|
+
<template #nav><!-- nav links --></template>
|
|
38
|
+
<template #actions>
|
|
39
|
+
<ColorModeControl v-model="mode" />
|
|
40
|
+
</template>
|
|
41
|
+
</AppHeader>
|
|
42
|
+
|
|
43
|
+
<AppSidebar variant="light">
|
|
44
|
+
<template #head><!-- sidebar header --></template>
|
|
45
|
+
<template #default>
|
|
46
|
+
<SidebarItem label="Overview" :active="true" />
|
|
47
|
+
<SidebarItem label="Settings" />
|
|
48
|
+
</template>
|
|
49
|
+
<template #foot><!-- sidebar footer --></template>
|
|
50
|
+
</AppSidebar>
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
## Colour mode
|
|
54
|
+
|
|
55
|
+
```ts
|
|
56
|
+
import { useColorMode } from '@meddleware/ui'
|
|
57
|
+
import type { ColorMode } from '@meddleware/ui'
|
|
58
|
+
|
|
59
|
+
const { mode } = useColorMode() // ColorMode: 'light' | 'dark' | 'system'
|
|
60
|
+
mode.value = 'dark' // sets data-theme="dark" on <html>, persists to localStorage
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
`ColorModeControl` is a presentational toggle — bind with `v-model`:
|
|
64
|
+
|
|
65
|
+
```vue
|
|
66
|
+
<ColorModeControl v-model="mode" />
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
## Primitives
|
|
70
|
+
|
|
71
|
+
| Component | Props | Notes |
|
|
72
|
+
| --- | --- | --- |
|
|
73
|
+
| `UiButton` | native `<button>` attrs | Styled with `--accent`, `--focus-ring`, `--transition-base` |
|
|
74
|
+
| `UiCard` | — | `--surface` background, `--border`, `--radius` |
|
|
75
|
+
| `UiSelect` | native `<select>` attrs | Styled with scale tokens; `--focus-ring` on focus |
|
|
76
|
+
| `UiNotice` | `variant: 'info' \| 'warning' \| 'danger' \| 'ok'` | Uses status role tokens |
|
|
77
|
+
| `SidebarItem` | `label`, `icon?`, `active?`, `disabled?` | Navigation item for `AppSidebar` |
|
|
78
|
+
| `CopyableAddress` | `address`, `truncate?`, `chars?`, `label?` | Copy-to-clipboard with icon; slot for link |
|
|
79
|
+
| `ExplorerLink` | `href`, `value?` | External block-explorer link; compose inside `CopyableAddress` |
|
|
80
|
+
|
|
81
|
+
### Copy + link pattern
|
|
82
|
+
|
|
83
|
+
```vue
|
|
84
|
+
<CopyableAddress :address="addr">
|
|
85
|
+
<ExplorerLink :href="suiExplorerUrl('account', addr, 'testnet')" :value="addr" />
|
|
86
|
+
</CopyableAddress>
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
### Explorer helper
|
|
90
|
+
|
|
91
|
+
```ts
|
|
92
|
+
import { suiExplorerUrl } from '@meddleware/ui'
|
|
93
|
+
|
|
94
|
+
const url = suiExplorerUrl('txblock', txDigest, 'testnet')
|
|
95
|
+
// → https://suiscan.xyz/testnet/tx/<txDigest>
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
Supported kinds: `'account'`, `'object'`, `'txblock'`. Network defaults to `'testnet'`.
|
|
99
|
+
|
|
100
|
+
## CSS utilities (`base.css`)
|
|
101
|
+
|
|
102
|
+
Import `@meddleware/ui/base.css` to get element-level defaults and opt-in utility classes:
|
|
103
|
+
|
|
104
|
+
| Class | Effect |
|
|
105
|
+
| --- | --- |
|
|
106
|
+
| `.mw-noise` | Applies `--noise-overlay` as a `::before` layer — controlled imperfection |
|
|
107
|
+
| `.mw-spinner` | Sigil-like ring loader animation (settles on `prefers-reduced-motion`) |
|
|
108
|
+
| `.mw-hand-drawn` | Empty positioned hook — drop an `<svg>` or `<canvas>` inside for bespoke illustration |
|
|
109
|
+
| `.mw-mono` | Monospace font via `--mw-font-mono` |
|
|
110
|
+
|
|
111
|
+
All animations respect `prefers-reduced-motion`.
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
# Design system
|
|
2
|
+
|
|
3
|
+
The Meddleware design system is two packages:
|
|
4
|
+
|
|
5
|
+
- **`@meddleware/design-tokens`** — CSS custom properties, JSON token tree, and TypeScript exports. The source of truth for colours, spacing, type scale, and motion.
|
|
6
|
+
- **`@meddleware/ui`** — Vue 3 component library (layout shell, primitives, colour-mode control) built entirely on the token layer.
|
|
7
|
+
|
|
8
|
+
## Quick start
|
|
9
|
+
|
|
10
|
+
```bash
|
|
11
|
+
npm install @meddleware/design-tokens @meddleware/ui
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
Import the CSS once at your app entry point:
|
|
15
|
+
|
|
16
|
+
```ts
|
|
17
|
+
// src/main.ts
|
|
18
|
+
import '@meddleware/design-tokens/tokens.css' // required — registers CSS custom properties
|
|
19
|
+
import '@meddleware/design-tokens/seasons.css' // optional — data-season="spring|summer|autumn|winter"
|
|
20
|
+
import '@meddleware/ui/base.css' // optional — element defaults + scale + utilities
|
|
21
|
+
import { createApp } from 'vue'
|
|
22
|
+
import App from './App.vue'
|
|
23
|
+
|
|
24
|
+
createApp(App).mount('#app')
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
## Philosophy
|
|
28
|
+
|
|
29
|
+
The design system is guided by three principles:
|
|
30
|
+
|
|
31
|
+
1. **Design recedes** — structure is invisible (sacred-geometry scales, φ/Fibonacci spacing). No decorative chrome.
|
|
32
|
+
2. **Primary colours as functional accents** — red = accent/action, blue = secondary/info, yellow = warning, green = ok. No gold or purple as identity marks.
|
|
33
|
+
3. **Controlled imperfection** — subtle noise, asymmetric spacing hooks, human easing. Machines are smooth; the design has texture.
|
|
34
|
+
|
|
35
|
+
## Token layers
|
|
36
|
+
|
|
37
|
+
| Layer | Purpose | Example |
|
|
38
|
+
| --- | --- | --- |
|
|
39
|
+
| Palette ramps | Colour-named; expandable swatches | `--mw-red-500`, `--mw-blue-300` |
|
|
40
|
+
| Semantic roles | Colour-agnostic; what components use | `--accent`, `--warning`, `--focus-ring` |
|
|
41
|
+
| Sacred-geometry scales | φ/Fibonacci spacing and type | `--space-md`, `--font-size-lg` |
|
|
42
|
+
| Panel palettes | Theme-independent (for shell variants) | `--mw-panel-dark-bg` |
|
|
43
|
+
| Chaos/motion | Noise, asymmetry, transitions | `--noise-overlay`, `--transition-base` |
|
|
44
|
+
|
|
45
|
+
See [Design tokens](./tokens) for full usage, and [Components](./components) for the component API.
|
|
46
|
+
|
|
47
|
+
## Light / dark mode
|
|
48
|
+
|
|
49
|
+
`useColorMode` from `@meddleware/ui` manages the `data-theme="dark"` attribute on `<html>` and persists to localStorage. All semantic tokens flip automatically.
|
|
50
|
+
|
|
51
|
+
```vue
|
|
52
|
+
<script setup>
|
|
53
|
+
import { AppHeader, ColorModeControl, useColorMode } from '@meddleware/ui'
|
|
54
|
+
const { mode } = useColorMode()
|
|
55
|
+
</script>
|
|
56
|
+
|
|
57
|
+
<template>
|
|
58
|
+
<AppHeader variant="dark">
|
|
59
|
+
<template #actions>
|
|
60
|
+
<ColorModeControl v-model="mode" />
|
|
61
|
+
</template>
|
|
62
|
+
</AppHeader>
|
|
63
|
+
</template>
|
|
64
|
+
```
|
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
# Design tokens
|
|
2
|
+
|
|
3
|
+
`@meddleware/design-tokens` ships four entry points:
|
|
4
|
+
|
|
5
|
+
| Import | Use |
|
|
6
|
+
| --- | --- |
|
|
7
|
+
| `@meddleware/design-tokens/tokens.css` | CSS custom properties — **always required** |
|
|
8
|
+
| `@meddleware/design-tokens/seasons.css` | Optional seasonal accent overrides |
|
|
9
|
+
| `@meddleware/design-tokens/tokens.json` | Raw JSON token tree for tooling |
|
|
10
|
+
| `@meddleware/design-tokens` (JS) | TypeScript re-export of the token tree |
|
|
11
|
+
|
|
12
|
+
## Two-layer naming discipline
|
|
13
|
+
|
|
14
|
+
**Layer 1 — palette/ramp (colour-named):** These are the raw hue swatches. Components never reference them directly.
|
|
15
|
+
|
|
16
|
+
```css
|
|
17
|
+
--mw-red-500 --mw-red-300 --mw-red-600
|
|
18
|
+
--mw-blue-500 --mw-blue-300
|
|
19
|
+
--mw-yellow-400 --mw-green-500
|
|
20
|
+
/* …and legacy brand ramps: --mw-oxblood-*, --mw-indigo-*, --mw-gold-* */
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
**Layer 2 — semantic roles (colour-agnostic):** What your components and apps should use. Revaluing them later never requires renaming.
|
|
24
|
+
|
|
25
|
+
```css
|
|
26
|
+
--accent /* primary action (red) */
|
|
27
|
+
--secondary /* secondary action (blue) */
|
|
28
|
+
--warning /* caution/advisory (yellow) */
|
|
29
|
+
--ok /* success/positive (green) */
|
|
30
|
+
--danger /* error/destructive (red) */
|
|
31
|
+
--info /* informational (blue) */
|
|
32
|
+
--focus-ring /* keyboard focus indicator */
|
|
33
|
+
--highlight /* text emphasis (yellow) */
|
|
34
|
+
--bg --surface --text --muted --border --lift
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## Sacred-geometry scales
|
|
38
|
+
|
|
39
|
+
All spacing and type sizes are derived from the golden ratio (φ = 1.618) via `calc()`. Nothing is a magic number.
|
|
40
|
+
|
|
41
|
+
### Spacing (Fibonacci)
|
|
42
|
+
|
|
43
|
+
```css
|
|
44
|
+
--space-3xs: 0.25rem /* 4px */
|
|
45
|
+
--space-2xs: 0.5rem /* 8px */
|
|
46
|
+
--space-xs: 0.75rem /* 12px */
|
|
47
|
+
--space-sm: 1.25rem /* 20px */
|
|
48
|
+
--space-md: 2rem /* 32px */
|
|
49
|
+
--space-lg: 3.25rem /* 52px */
|
|
50
|
+
--space-xl: 5.25rem /* 84px */
|
|
51
|
+
--space-2xl: 8.5rem /* 136px */
|
|
52
|
+
--space-3xl: 13.75rem /* 220px */
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
### Type scale (φ-derived modular)
|
|
56
|
+
|
|
57
|
+
```css
|
|
58
|
+
--font-size-base: 1rem
|
|
59
|
+
--font-size-sm: calc(var(--font-size-base) / var(--ratio-phi-root)) /* ~0.787rem */
|
|
60
|
+
--font-size-lg: calc(var(--font-size-base) * var(--ratio-phi-root)) /* ~1.272rem */
|
|
61
|
+
--font-size-xl: calc(var(--font-size-base) * var(--ratio-phi)) /* ~1.618rem */
|
|
62
|
+
--font-size-2xl: calc(var(--font-size-xl) * var(--ratio-phi)) /* ~2.618rem */
|
|
63
|
+
--font-size-3xl: calc(var(--font-size-2xl) * var(--ratio-phi)) /* ~4.236rem */
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
### Ratios and splits
|
|
67
|
+
|
|
68
|
+
```css
|
|
69
|
+
--ratio-phi: 1.618
|
|
70
|
+
--ratio-phi-inv: 0.618
|
|
71
|
+
--ratio-phi-root: 1.272
|
|
72
|
+
--split-major: 61.8% /* φ-split: use for hero/content layouts */
|
|
73
|
+
--split-minor: 38.2%
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
## Seasonal theming
|
|
77
|
+
|
|
78
|
+
Import `seasons.css` and set `data-season` on `<html>` (or any ancestor). The season overrides accent, highlight, status tints, and a faint background tint. Dark mode composes independently.
|
|
79
|
+
|
|
80
|
+
```ts
|
|
81
|
+
// Enable seasonal theming
|
|
82
|
+
import '@meddleware/design-tokens/seasons.css'
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
```html
|
|
86
|
+
<!-- Spring: green/yellow accents -->
|
|
87
|
+
<html data-season="spring">
|
|
88
|
+
|
|
89
|
+
<!-- Summer: bright blue/red -->
|
|
90
|
+
<html data-season="summer">
|
|
91
|
+
|
|
92
|
+
<!-- Autumn: orange/amber -->
|
|
93
|
+
<html data-season="autumn">
|
|
94
|
+
|
|
95
|
+
<!-- Winter: cool blue/desaturated -->
|
|
96
|
+
<html data-season="winter">
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
Seasons compose with `data-theme`:
|
|
100
|
+
|
|
101
|
+
```html
|
|
102
|
+
<html data-theme="dark" data-season="winter">
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
To override a single role while keeping seasonal fallback:
|
|
106
|
+
|
|
107
|
+
```css
|
|
108
|
+
/* In your app's CSS — defines --season-accent for the current season scope */
|
|
109
|
+
:root {
|
|
110
|
+
--season-accent: #0066cc; /* overrides the spring/summer/etc. accent locally */
|
|
111
|
+
}
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
Not importing `seasons.css` is a valid opt-out — every role uses its light/dark primary fallback silently. No console warnings.
|
|
115
|
+
|
|
116
|
+
## Chaos and motion tokens
|
|
117
|
+
|
|
118
|
+
```css
|
|
119
|
+
--noise-overlay /* SVG noise layer (use with .mw-noise utility class) */
|
|
120
|
+
--noise-opacity: 0.035
|
|
121
|
+
--hero-offset /* φ-derived horizontal offset for intentional asymmetry */
|
|
122
|
+
--gap-irregular /* slightly non-uniform gap for human presence */
|
|
123
|
+
--transition-base: 140ms cubic-bezier(0.2, 0, 0.2, 1)
|
|
124
|
+
--transition-slow: 320ms cubic-bezier(0.2, 0, 0.2, 1)
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
## TypeScript / JSON usage
|
|
128
|
+
|
|
129
|
+
```ts
|
|
130
|
+
import { primary, ratio, space, semantic } from '@meddleware/design-tokens'
|
|
131
|
+
|
|
132
|
+
console.log(primary.red[500]) // "#d92d20"
|
|
133
|
+
console.log(ratio.phi) // 1.618
|
|
134
|
+
console.log(space.md) // "2rem"
|
|
135
|
+
console.log(semantic.dark.accent) // "#ef5a4c"
|
|
136
|
+
```
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
# Getting started
|
|
2
|
+
|
|
3
|
+
Everything you need to build on the Meddleware platform.
|
|
4
|
+
|
|
5
|
+
## Prerequisites at a glance
|
|
6
|
+
|
|
7
|
+
| Tool | Minimum version | Notes |
|
|
8
|
+
| --- | --- | --- |
|
|
9
|
+
| Node.js | 22.18.0 or ≥ 24.12.0 | LTS recommended |
|
|
10
|
+
| npm | 10+ | Ships with Node |
|
|
11
|
+
| Sui CLI | testnet v1.76.1 | Managed via [suiup](#suiup) |
|
|
12
|
+
| Walrus CLI | testnet v1.53.0 | Managed via suiup |
|
|
13
|
+
| Docker | any recent | For running services locally |
|
|
14
|
+
|
|
15
|
+
See [Toolchain](./toolchain) for installation steps and version pinning.
|
|
16
|
+
|
|
17
|
+
## What you can build
|
|
18
|
+
|
|
19
|
+
The Meddleware platform provides four composable tools on Sui:
|
|
20
|
+
|
|
21
|
+
- **Walrus Storage** — upload files to Walrus decentralised storage via a relay with optional NFT gating and tips.
|
|
22
|
+
- **Sealed Storage** — encrypt data on Walrus with on-chain access policies enforced by Move smart contracts.
|
|
23
|
+
- **Access Gate** — create and sell NFT access passes that gate content, relay access, or any on-chain action.
|
|
24
|
+
- **DAO** — a governance layer that controls vault parameters, fee configuration, and strategy allocation.
|
|
25
|
+
|
|
26
|
+
The tools compose: a gated Walrus relay uses Access Gate passes; Sealed Storage policies can require an Access Gate pass; the vault earns yield which flows through the DAO.
|
|
27
|
+
|
|
28
|
+
## Quick orientation
|
|
29
|
+
|
|
30
|
+
```text
|
|
31
|
+
workspace/
|
|
32
|
+
├── repos/
|
|
33
|
+
│ ├── docs/ ← user-facing docs (docs.meddleware.co.uk)
|
|
34
|
+
│ ├── dev/ ← this site (dev.meddleware.co.uk)
|
|
35
|
+
│ ├── walrus-ui/ ← Walrus Storage app
|
|
36
|
+
│ ├── seal-ui/ ← Sealed Storage app
|
|
37
|
+
│ ├── access-gate-ui/← Access Gate app
|
|
38
|
+
│ └── dao-ui/ ← DAO console
|
|
39
|
+
├── blockchain/
|
|
40
|
+
│ └── sui/
|
|
41
|
+
│ ├── contracts/ ← Move smart contracts
|
|
42
|
+
│ └── packages/ ← TypeScript SDK packages
|
|
43
|
+
├── post-bootstrap/ ← Kubernetes deployment manifests
|
|
44
|
+
└── config/ ← central image registry config
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## Next steps
|
|
48
|
+
|
|
49
|
+
- [Toolchain](./toolchain) — install the CLI tools
|
|
50
|
+
- [Local development](./local-dev) — run the platform locally
|
|
51
|
+
- [Design system](../design-system/) — build a Vue app on the token/component layer
|
|
52
|
+
- [Sui development](../sui/) — PTBs, environment setup, and service-by-service guides
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
# Local development
|
|
2
|
+
|
|
3
|
+
## Running a specific app
|
|
4
|
+
|
|
5
|
+
Each app in `repos/` has a local dev server:
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
cd repos/walrus-ui && npm run dev # http://localhost:5173
|
|
9
|
+
cd repos/seal-ui && npm run dev
|
|
10
|
+
cd repos/access-gate-ui && npm run dev
|
|
11
|
+
cd repos/dao-ui && npm run dev
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
All apps read environment variables from `.env.local` (git-ignored). Copy the example file to get started:
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
cp .env.example .env.local
|
|
18
|
+
# Edit VITE_NETWORK=testnet, VITE_DOCS_URL, VITE_DEV_URL, etc.
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
## Running this docs site locally
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
cd repos/dev
|
|
25
|
+
npm install
|
|
26
|
+
npm run dev # http://localhost:5173
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
For the user-facing docs site:
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
cd repos/docs
|
|
33
|
+
npm install
|
|
34
|
+
npm run dev # gen:api runs first (requires @meddleware/* SDK packages published)
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## Environment variables
|
|
38
|
+
|
|
39
|
+
Common variables shared across apps:
|
|
40
|
+
|
|
41
|
+
| Variable | Default | Notes |
|
|
42
|
+
| --- | --- | --- |
|
|
43
|
+
| `VITE_NETWORK` | `testnet` | `localnet` \| `testnet` \| `mainnet` |
|
|
44
|
+
| `VITE_DOCS_URL` | `https://docs.meddleware.co.uk` | User docs base URL |
|
|
45
|
+
| `VITE_DEV_URL` | `https://dev.meddleware.co.uk` | Developer docs base URL |
|
|
46
|
+
| `VITE_API_BASE` | `` (same-origin) | Override API host (status-page, etc.) |
|
|
47
|
+
|
|
48
|
+
Per-service variables (e.g. `VITE_WALRUS_PUBLISHER_URL`, `VITE_NFT_GATE_URL`) are documented in each app's `.env.example`.
|
|
49
|
+
|
|
50
|
+
## Docker builds
|
|
51
|
+
|
|
52
|
+
To build and run any service as a Docker image (requires Docker Desktop or similar):
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
cd repos/walrus-ui
|
|
56
|
+
docker build -t walrus-ui:dev .
|
|
57
|
+
docker run -p 8080:8080 walrus-ui:dev
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
The `SPA_FALLBACK=true` env var is baked in — the static-server handles client-side routing.
|
|
61
|
+
|
|
62
|
+
## Move contracts (localnet)
|
|
63
|
+
|
|
64
|
+
For local contract development, start a localnet and publish the contracts:
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
sui start --with-faucet # starts localnet on :9000; press Ctrl+C to stop
|
|
68
|
+
# In another terminal:
|
|
69
|
+
cd blockchain/sui/contracts/core
|
|
70
|
+
sui move build --build-env localnet
|
|
71
|
+
sui client publish --gas-budget 200000000
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
See [Environment setup](../sui/environment) for a full localnet workflow.
|