dekit-cli 0.4.0 → 0.4.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/README.md +24 -19
- package/docs/usage.md +186 -54
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -15,6 +15,18 @@ Agent creates design → dekit renders it → Agent screenshots to check
|
|
|
15
15
|
- Human opens the browser preview, inspects elements, and gives feedback using refs
|
|
16
16
|
- Agent resolves the feedback to exact source code locations and iterates
|
|
17
17
|
|
|
18
|
+
All design files live inside a `.dekit/` directory, keeping your project clean:
|
|
19
|
+
|
|
20
|
+
```
|
|
21
|
+
your-project/
|
|
22
|
+
└── .dekit/
|
|
23
|
+
├── dekit.yaml ← config
|
|
24
|
+
├── global.css
|
|
25
|
+
├── pages/
|
|
26
|
+
├── components/
|
|
27
|
+
└── screenshots/
|
|
28
|
+
```
|
|
29
|
+
|
|
18
30
|
## Getting Started
|
|
19
31
|
|
|
20
32
|
### 1. Install
|
|
@@ -38,7 +50,7 @@ Follow the guide to complete your design task.
|
|
|
38
50
|
|
|
39
51
|
## Examples
|
|
40
52
|
|
|
41
|
-
**
|
|
53
|
+
**Design a landing page:**
|
|
42
54
|
|
|
43
55
|
```
|
|
44
56
|
> Use dekit to design a landing page for a task management app
|
|
@@ -46,40 +58,33 @@ Follow the guide to complete your design task.
|
|
|
46
58
|
|
|
47
59
|
The agent handles everything — project setup, writing HTML/CSS, taking screenshots to verify, and iterating on the design.
|
|
48
60
|
|
|
49
|
-
**
|
|
50
|
-
|
|
51
|
-
When the agent starts the preview server, open the browser to review. Right-click any element and **Copy Ref**, then tell the agent what to change:
|
|
61
|
+
**Design for mobile:**
|
|
52
62
|
|
|
53
63
|
```
|
|
54
|
-
>
|
|
64
|
+
> Use dekit to design a mobile app for a fitness tracker, use the mobile template
|
|
55
65
|
```
|
|
56
66
|
|
|
57
|
-
**
|
|
67
|
+
**Add to an existing project:**
|
|
58
68
|
|
|
59
69
|
```
|
|
60
|
-
> Initialize a dekit design project
|
|
70
|
+
> Initialize a dekit design project using the dashboard template
|
|
61
71
|
```
|
|
62
72
|
|
|
63
|
-
The agent creates a
|
|
73
|
+
The agent creates a `.dekit/` directory with all the scaffolding, without touching your existing code.
|
|
64
74
|
|
|
65
|
-
**
|
|
66
|
-
|
|
67
|
-
```
|
|
68
|
-
> Create a ui-card component with an image slot and body slot, then build a showcase page that uses it
|
|
69
|
-
```
|
|
70
|
-
|
|
71
|
-
The agent creates Web Components with `<template>` + scoped CSS, registers them in `dekit.yaml`, and uses them in pages like `<ui-card>`.
|
|
75
|
+
**Review and give feedback:**
|
|
72
76
|
|
|
73
|
-
|
|
77
|
+
When the agent starts the preview server, open the browser to review. Right-click any element and **Copy Ref**, then tell the agent what to change:
|
|
74
78
|
|
|
75
79
|
```
|
|
76
|
-
>
|
|
80
|
+
> The hero section $${home@.hero} needs more padding, and make the CTA button blue
|
|
77
81
|
```
|
|
78
82
|
|
|
79
|
-
**
|
|
83
|
+
**Add pages and components:**
|
|
80
84
|
|
|
81
85
|
```
|
|
82
|
-
>
|
|
86
|
+
> Add a pricing page with a 3-tier card layout
|
|
87
|
+
> Create a ui-card component with an image slot and body slot
|
|
83
88
|
```
|
|
84
89
|
|
|
85
90
|
## License
|
package/docs/usage.md
CHANGED
|
@@ -1,52 +1,184 @@
|
|
|
1
1
|
# Dekit — Agent Usage Guide
|
|
2
2
|
|
|
3
|
-
Dekit is a design canvas for code agents. You
|
|
3
|
+
Dekit is a design canvas for code agents. You create HTML/CSS designs, dekit renders them, and you take screenshots to see the result.
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## Project Structure
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
7
|
+
All design files live inside a `.dekit/` directory:
|
|
8
|
+
|
|
9
|
+
```
|
|
10
|
+
project/
|
|
11
|
+
└── .dekit/
|
|
12
|
+
├── dekit.yaml ← config (pages, components, global style)
|
|
13
|
+
├── global.css ← shared styles across all pages
|
|
14
|
+
├── pages/
|
|
15
|
+
│ └── home/
|
|
16
|
+
│ ├── home.html ← page template (plain HTML, no framework)
|
|
17
|
+
│ └── home.css ← page-specific styles
|
|
18
|
+
├── components/
|
|
19
|
+
│ └── ui-card/
|
|
20
|
+
│ ├── ui-card.html ← Web Component template
|
|
21
|
+
│ └── ui-card.css ← component scoped styles
|
|
22
|
+
└── screenshots/ ← generated by dekit screenshot
|
|
23
|
+
```
|
|
10
24
|
|
|
11
25
|
## Quick Start
|
|
12
26
|
|
|
13
27
|
```bash
|
|
14
|
-
# Initialize
|
|
15
|
-
dekit init
|
|
28
|
+
# 1. Initialize (creates .dekit/ in current directory)
|
|
29
|
+
dekit init --template landing
|
|
16
30
|
|
|
17
|
-
#
|
|
18
|
-
cd my-design
|
|
19
|
-
dekit serve
|
|
20
|
-
|
|
21
|
-
# Take a screenshot
|
|
31
|
+
# 2. Take a screenshot to see the design
|
|
22
32
|
dekit screenshot '$${home}'
|
|
33
|
+
|
|
34
|
+
# 3. The screenshot is saved to .dekit/screenshots/home.png
|
|
35
|
+
# Read the screenshot file to see the result, then iterate
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
## Writing Pages
|
|
39
|
+
|
|
40
|
+
Pages are plain HTML — no framework, no build step. Write standard HTML tags and CSS.
|
|
41
|
+
|
|
42
|
+
**Page HTML** (`.dekit/pages/home/home.html`):
|
|
43
|
+
```html
|
|
44
|
+
<header class="hero">
|
|
45
|
+
<h1>Welcome</h1>
|
|
46
|
+
<p>A short description.</p>
|
|
47
|
+
<a class="cta" href="#">Get Started</a>
|
|
48
|
+
</header>
|
|
49
|
+
|
|
50
|
+
<section class="features">
|
|
51
|
+
<div class="feature">
|
|
52
|
+
<h3>Fast</h3>
|
|
53
|
+
<p>Lightning quick performance.</p>
|
|
54
|
+
</div>
|
|
55
|
+
</section>
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
**Page CSS** (`.dekit/pages/home/home.css`):
|
|
59
|
+
```css
|
|
60
|
+
.hero {
|
|
61
|
+
display: flex;
|
|
62
|
+
flex-direction: column;
|
|
63
|
+
align-items: center;
|
|
64
|
+
padding: 96px 24px;
|
|
65
|
+
gap: 16px;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
.cta {
|
|
69
|
+
padding: 12px 32px;
|
|
70
|
+
background: var(--color-primary);
|
|
71
|
+
color: #fff;
|
|
72
|
+
border-radius: 8px;
|
|
73
|
+
text-decoration: none;
|
|
74
|
+
}
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Key rules:
|
|
78
|
+
- Write the `<body>` content only — no `<html>`, `<head>`, or `<body>` tags (dekit wraps it)
|
|
79
|
+
- Use CSS variables from `global.css` (e.g. `var(--color-primary)`)
|
|
80
|
+
- Each page has its own HTML + CSS file pair
|
|
81
|
+
|
|
82
|
+
## Writing Components
|
|
83
|
+
|
|
84
|
+
Components use Web Components (custom elements with Shadow DOM). The tag name **must contain a hyphen**.
|
|
85
|
+
|
|
86
|
+
**Component HTML** (`.dekit/components/ui-card/ui-card.html`):
|
|
87
|
+
```html
|
|
88
|
+
<template>
|
|
89
|
+
<div class="card">
|
|
90
|
+
<div class="card-image">
|
|
91
|
+
<slot name="image"></slot>
|
|
92
|
+
</div>
|
|
93
|
+
<div class="card-body">
|
|
94
|
+
<slot></slot>
|
|
95
|
+
</div>
|
|
96
|
+
</div>
|
|
97
|
+
</template>
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
**Component CSS** (`.dekit/components/ui-card/ui-card.css`):
|
|
101
|
+
```css
|
|
102
|
+
.card {
|
|
103
|
+
border: 1px solid #e5e7eb;
|
|
104
|
+
border-radius: 12px;
|
|
105
|
+
overflow: hidden;
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
.card-body {
|
|
109
|
+
padding: 16px;
|
|
110
|
+
}
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
**Using components in pages:**
|
|
114
|
+
```html
|
|
115
|
+
<ui-card>
|
|
116
|
+
<img slot="image" src="photo.jpg">
|
|
117
|
+
<h3>Title</h3>
|
|
118
|
+
<p>Description</p>
|
|
119
|
+
</ui-card>
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
Key rules:
|
|
123
|
+
- Wrap content in `<template>` tags
|
|
124
|
+
- Use `<slot></slot>` for default content, `<slot name="x"></slot>` for named slots
|
|
125
|
+
- CSS is scoped to the component (Shadow DOM) — styles don't leak
|
|
126
|
+
- Use `:host` selector to style the component element itself
|
|
127
|
+
- Use `::slotted(*)` to style slotted content
|
|
128
|
+
|
|
129
|
+
## dekit.yaml
|
|
130
|
+
|
|
131
|
+
Every page and component must be registered:
|
|
132
|
+
|
|
133
|
+
```yaml
|
|
134
|
+
version: 1.0
|
|
135
|
+
global-style: "global.css"
|
|
136
|
+
|
|
137
|
+
components:
|
|
138
|
+
ui-card:
|
|
139
|
+
template: "components/ui-card/ui-card.html"
|
|
140
|
+
style: "components/ui-card/ui-card.css"
|
|
141
|
+
|
|
142
|
+
pages:
|
|
143
|
+
home:
|
|
144
|
+
template: "pages/home/home.html"
|
|
145
|
+
style: "pages/home/home.css"
|
|
146
|
+
about:
|
|
147
|
+
template: "pages/about/about.html"
|
|
148
|
+
style: "pages/about/about.css"
|
|
23
149
|
```
|
|
24
150
|
|
|
151
|
+
All paths are relative to the `.dekit/` directory.
|
|
152
|
+
|
|
25
153
|
## CLI Reference
|
|
26
154
|
|
|
27
155
|
### dekit init [path] [--template name]
|
|
28
156
|
|
|
29
|
-
Initialize a design project.
|
|
157
|
+
Initialize a design project. Creates `.dekit/` directory under the target path (default: current directory).
|
|
158
|
+
|
|
159
|
+
Templates: `blank`, `landing`, `dashboard`, `mobile`.
|
|
30
160
|
|
|
31
161
|
```bash
|
|
32
|
-
dekit init #
|
|
33
|
-
dekit init
|
|
162
|
+
dekit init # .dekit/ in current directory
|
|
163
|
+
dekit init my-project # my-project/.dekit/
|
|
34
164
|
dekit init --template landing # With template
|
|
35
165
|
dekit init --template # List available templates
|
|
36
166
|
```
|
|
37
167
|
|
|
38
|
-
### dekit add page
|
|
168
|
+
### dekit add page \<name\> [--template name]
|
|
169
|
+
|
|
170
|
+
Add a page. Creates files and updates dekit.yaml.
|
|
39
171
|
|
|
40
|
-
|
|
172
|
+
Templates: `blank`, `hero`, `form`, `grid`.
|
|
41
173
|
|
|
42
174
|
```bash
|
|
43
175
|
dekit add page about
|
|
44
176
|
dekit add page pricing --template grid
|
|
45
177
|
```
|
|
46
178
|
|
|
47
|
-
### dekit add component
|
|
179
|
+
### dekit add component \<name\>
|
|
48
180
|
|
|
49
|
-
Add a Web Component (name must contain a hyphen).
|
|
181
|
+
Add a Web Component (name must contain a hyphen). Creates files and updates dekit.yaml.
|
|
50
182
|
|
|
51
183
|
```bash
|
|
52
184
|
dekit add component my-card
|
|
@@ -54,35 +186,35 @@ dekit add component my-card
|
|
|
54
186
|
|
|
55
187
|
### dekit ls
|
|
56
188
|
|
|
57
|
-
List all pages and components.
|
|
189
|
+
List all pages and components in the project.
|
|
58
190
|
|
|
59
191
|
### dekit serve [-p port] [--no-open]
|
|
60
192
|
|
|
61
|
-
Start the interactive preview server.
|
|
193
|
+
Start the interactive preview server (default port: 7980). Use this when a human wants to review the design in a browser.
|
|
62
194
|
|
|
63
|
-
### dekit screenshot
|
|
195
|
+
### dekit screenshot \<ref\>
|
|
64
196
|
|
|
65
|
-
Take a screenshot.
|
|
197
|
+
Take a screenshot. The output file path is printed to stdout — read that file to see the result.
|
|
66
198
|
|
|
67
199
|
```bash
|
|
68
|
-
dekit screenshot '$${home}' # Full page
|
|
200
|
+
dekit screenshot '$${home}' # Full page → .dekit/screenshots/home.png
|
|
69
201
|
dekit screenshot '$${home@.hero}' # Element only
|
|
70
202
|
dekit screenshot '$${home}' --device iphone-14 # Device size
|
|
71
|
-
dekit screenshot '$${home}' --full-page # Include scroll
|
|
72
|
-
dekit screenshot '$${home}' -o
|
|
203
|
+
dekit screenshot '$${home}' --full-page # Include scroll area
|
|
204
|
+
dekit screenshot '$${home}' -o output.png # Custom output path
|
|
73
205
|
dekit screenshot --all # All pages
|
|
74
206
|
```
|
|
75
207
|
|
|
76
|
-
### dekit resolve
|
|
208
|
+
### dekit resolve \<ref\>
|
|
77
209
|
|
|
78
|
-
Resolve a ref to source file path and line range.
|
|
210
|
+
Resolve a ref to the source file path and line range. Use this when a human gives you a ref and you need to find the code to edit.
|
|
79
211
|
|
|
80
212
|
```bash
|
|
81
213
|
dekit resolve '$${home}'
|
|
82
|
-
# → pages/home/home.html
|
|
214
|
+
# → .dekit/pages/home/home.html
|
|
83
215
|
|
|
84
216
|
dekit resolve '$${home@.hero}'
|
|
85
|
-
# → pages/home/home.html:1-10
|
|
217
|
+
# → .dekit/pages/home/home.html:1-10
|
|
86
218
|
```
|
|
87
219
|
|
|
88
220
|
### dekit usage
|
|
@@ -91,37 +223,37 @@ Print this guide.
|
|
|
91
223
|
|
|
92
224
|
## Ref Protocol
|
|
93
225
|
|
|
94
|
-
Format: `$${page-key}` or `$${page-key@css-selector}
|
|
226
|
+
Refs identify pages and elements. Format: `$${page-key}` or `$${page-key@css-selector}`.
|
|
95
227
|
|
|
96
|
-
When you see a `$${...}` pattern
|
|
228
|
+
When you see a `$${...}` pattern in user messages:
|
|
229
|
+
- `dekit resolve <ref>` → find the source file and line range to edit
|
|
230
|
+
- `dekit screenshot <ref>` → take a screenshot of that page or element
|
|
97
231
|
|
|
98
|
-
|
|
99
|
-
- `dekit screenshot <ref>` → screenshot file path
|
|
232
|
+
You don't need to parse refs yourself — just pass them to the CLI.
|
|
100
233
|
|
|
101
|
-
## Design
|
|
234
|
+
## Design Workflow
|
|
235
|
+
|
|
236
|
+
### Self-directed design loop
|
|
102
237
|
|
|
103
238
|
```
|
|
104
|
-
1. dekit init --template landing
|
|
105
|
-
2. Edit
|
|
106
|
-
3. dekit
|
|
107
|
-
4.
|
|
108
|
-
5.
|
|
109
|
-
6.
|
|
239
|
+
1. dekit init --template landing # Start project
|
|
240
|
+
2. Edit .dekit/pages/home/home.html # Write HTML
|
|
241
|
+
3. Edit .dekit/pages/home/home.css # Write CSS
|
|
242
|
+
4. dekit screenshot '$${home}' # Take screenshot
|
|
243
|
+
5. Read the screenshot file # Analyze the result
|
|
244
|
+
6. Edit HTML/CSS to fix issues # Iterate
|
|
245
|
+
7. Repeat 4-6 until satisfied # Keep improving
|
|
246
|
+
8. dekit serve # Let human review
|
|
110
247
|
```
|
|
111
248
|
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
```yaml
|
|
115
|
-
version: 1.0
|
|
116
|
-
global-style: "global.css"
|
|
249
|
+
### Human feedback loop
|
|
117
250
|
|
|
118
|
-
|
|
119
|
-
my-card:
|
|
120
|
-
template: "components/my-card/my-card.html"
|
|
121
|
-
style: "components/my-card/my-card.css"
|
|
251
|
+
When a human reviews the design, they may give feedback with refs:
|
|
122
252
|
|
|
123
|
-
pages:
|
|
124
|
-
home:
|
|
125
|
-
template: "pages/home/home.html"
|
|
126
|
-
style: "pages/home/home.css"
|
|
127
253
|
```
|
|
254
|
+
"The hero section $${home@.hero} needs more padding"
|
|
255
|
+
```
|
|
256
|
+
|
|
257
|
+
1. `dekit resolve '$${home@.hero}'` → find the file and line range
|
|
258
|
+
2. Edit the CSS at that location
|
|
259
|
+
3. `dekit screenshot '$${home@.hero}'` → verify the change
|