Skip to content

Commit e1ec81d

Browse files
carloscuestacarloscuesta
committed
📝 Add AGENTS.md 
1 parent fe21507 commit e1ec81d

File tree

2 files changed

+267
-0
lines changed

2 files changed

+267
-0
lines changed

‎.vscodeignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,3 +5,4 @@ src/
55
.gitattributes
66
.husky
77
.github
8+
AGENTS.md

‎AGENTS.md‎

Lines changed: 266 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,266 @@
1+
# AGENTS.md
2+
3+
This document provides a comprehensive overview of the Sprinkles VSCode theme project for AI agents.
4+
5+
## Overview
6+
7+
**Sprinkles** is a VSCode color theme extension featuring vibrant syntax highlighting with carefully curated color palettes. It provides both dark and light theme variants with a unique "sprinkled" aesthetic inspired by colorful sprinkles on donuts.
8+
9+
### Key Features
10+
11+
- Dark and light theme variants
12+
- Comprehensive syntax highlighting for multiple languages
13+
- Carefully designed UI colors for VSCode interface elements
14+
- Terminal color customization
15+
- Git diff gutter indicators
16+
17+
## Architecture
18+
19+
### Project structure
20+
21+
```
22+
sprinkles-vscode/
23+
├── src/ # Source code
24+
│ ├── colors/ # Color palette definitions
25+
│ │ ├── index.ts # Color loader/selector
26+
│ │ ├── dark.ts # Dark theme color palette
27+
│ │ └── light.ts # Light theme color palette
28+
│ ├── theme.ts # Theme generator (main logic)
29+
│ └── index.ts # Build script entry point
30+
├── themes/ # Generated theme JSON files (output)
31+
│ ├── sprinkles-dark.json
32+
│ └── sprinkles-light.json
33+
├── images/ # Extension assets (icon)
34+
├── .vscode/ # VSCode configuration
35+
│ └── launch.json # Debug configuration
36+
└── package.json # Extension manifest & build config
37+
```
38+
39+
### Architecture flow
40+
41+
```
42+
┌─────────────────┐
43+
│ src/index.ts │ Entry point - orchestrates theme generation
44+
└────────┬────────┘
45+
│
46+
▼
47+
┌─────────────────┐
48+
│ src/theme.ts │ Theme generator - creates VSCode theme structure
49+
└────────┬────────┘
50+
│
51+
▼
52+
┌──────────────────┐
53+
│ src/colors/*.ts │ Color palettes - defines color schemes
54+
└──────────────────┘
55+
│
56+
▼
57+
┌──────────────────┐
58+
│ themes/*.json │ Output - VSCode theme files
59+
└──────────────────┘
60+
```
61+
62+
### Components
63+
64+
#### 1. **src/index.ts**
65+
66+
- Entry point for theme generation
67+
- Creates `themes/` directory if it doesn't exist
68+
- Generates both dark and light theme JSON files
69+
- Writes formatted JSON output with proper error handling
70+
71+
#### 2. **src/theme.ts**
72+
73+
- Core theme logic
74+
- Maps color palettes to VSCode theme properties
75+
- Defines token scopes for syntax highlighting
76+
- Returns complete VSCode theme object with:
77+
- Editor colors (background, foreground, cursor, etc.)
78+
- UI colors (activity bar, sidebar, status bar, etc.)
79+
- Terminal ANSI colors
80+
- Token colors (syntax highlighting rules)
81+
82+
#### 3. **src/colors/**
83+
84+
- `index.ts`: Exports color getter function based on variant
85+
- `dark.ts`: Dark theme color definitions
86+
- `light.ts`: Light theme color definitions
87+
- Color structure includes:
88+
- Canvas colors (UI elements)
89+
- Editor colors (code editor specific)
90+
- Terminal colors (ANSI color mappings)
91+
- Token colors (syntax highlighting)
92+
93+
#### 4. **package.json**
94+
95+
- VSCode extension manifest
96+
- Declares two theme contributions (dark and light)
97+
- Defines build scripts and dependencies
98+
- Extension metadata (name, version, publisher, etc.)
99+
100+
### Technology Stack
101+
102+
- **TypeScript**: Primary language
103+
- **Node.js**: Runtime environment
104+
- **ts-node**: TypeScript execution without compilation
105+
- **nodemon**: Development file watcher
106+
- **vsce**: VSCode Extension packager
107+
- **Prettier**: Code formatting
108+
- **Husky**: Git hooks for code quality
109+
110+
## Running the project
111+
112+
### Prerequisites
113+
114+
```bash
115+
npm install
116+
```
117+
118+
### Development
119+
120+
#### Build themes
121+
122+
Generate theme JSON files from source:
123+
124+
```bash
125+
npm run build
126+
```
127+
128+
This executes `ts-node ./src/index.ts` which:
129+
130+
1. Reads color definitions from `src/colors/`
131+
2. Generates theme objects via `src/theme.ts`
132+
3. Writes `themes/sprinkles-dark.json` and `themes/sprinkles-light.json`
133+
134+
#### Watch mode
135+
136+
Auto-rebuild themes on file changes:
137+
138+
```bash
139+
npm run dev
140+
```
141+
142+
Uses nodemon to watch `src/` directory and rebuild on changes.
143+
144+
### Testing the Theme
145+
146+
#### Method 1: Debug Mode
147+
148+
1. Open project in VSCode
149+
2. Press `F5` or go to Run & Debug panel
150+
3. Select "Extension" configuration
151+
4. Click "Start Debugging"
152+
5. A new VSCode window opens with the extension loaded
153+
6. Open Command Palette (`Cmd+Shift+P` or `Ctrl+Shift+P`)
154+
7. Select "Preferences: Color Theme"
155+
8. Choose "Sprinkles Dark" or "Sprinkles Light"
156+
157+
#### Method 2: Local Installation
158+
159+
```bash
160+
npm run publish:vsce -- --no-publish
161+
code --install-extension sprinkles-vscode-*.vsix
162+
```
163+
164+
### Code Quality
165+
166+
```bash
167+
npm run lint
168+
169+
npx prettier --write .
170+
```
171+
172+
## Debugging
173+
174+
1. **Using VSCode Debugger**:
175+
- Configuration is in `.vscode/launch.json`
176+
- Type: `extensionHost` (launches VSCode Extension Host)
177+
- Press `F5` to start debugging
178+
- Set breakpoints won't work (no runtime code, just JSON generation)
179+
180+
2. **Theme Generation**:
181+
182+
```bash
183+
# Add console.log statements in src/index.ts or src/theme.ts
184+
npm run build
185+
186+
# Or use Node debugger
187+
node --inspect-brk ./node_modules/.bin/ts-node ./src/index.ts
188+
```
189+
190+
3. **Theme Output**:
191+
- Inspect generated files: `themes/sprinkles-dark.json`
192+
- Use VSCode Developer Tools in extension host: `Help > Toggle Developer Tools`
193+
- Check theme token inspector: `Developer: Inspect Editor Tokens and Scopes`
194+
195+
### Common Issues
196+
197+
**Theme not updating in extension host:**
198+
199+
- Reload the extension host window (`Cmd+R` or `Ctrl+R`)
200+
- Or restart the debug session
201+
202+
**Colors not appearing correctly:**
203+
204+
- Check generated JSON files in `themes/` directory
205+
- Verify color definitions in `src/colors/dark.ts` or `light.ts`
206+
- Use token inspector to see applied scopes
207+
208+
**Build errors:**
209+
210+
- Ensure TypeScript files have no syntax errors
211+
- Check that all color properties are properly defined
212+
- Verify color values are valid hex codes
213+
214+
## Making Changes
215+
216+
### Adding New Colors
217+
218+
1. Edit color palettes:
219+
- Dark: `src/colors/dark.ts`
220+
- Light: `src/colors/light.ts`
221+
222+
2. Rebuild:
223+
224+
```bash
225+
npm run build
226+
```
227+
228+
3. Test in extension host (F5)
229+
230+
### Modifying Syntax Highlighting
231+
232+
1. Edit `src/theme.ts`
233+
2. Locate `tokenColors` array
234+
3. Add/modify scope rules:
235+
```typescript
236+
{
237+
name: "My Custom Token",
238+
scope: ["source.js meta.class"],
239+
settings: {
240+
foreground: colors.editor.tokens.amber,
241+
fontStyle: "italic"
242+
}
243+
}
244+
```
245+
4. Rebuild and test
246+
247+
### Changing UI Colors
248+
249+
1. Edit `colors` object in `src/theme.ts`
250+
2. Find VSCode theme key (e.g., `"activityBar.background"`)
251+
3. Map to color from palette
252+
4. Rebuild and test
253+
254+
## Publishing
255+
256+
```bash
257+
npm run publish:vsce
258+
```
259+
260+
Requires publisher credentials configured with `vsce`.
261+
262+
## Additional Resources
263+
264+
- [VSCode Theme Color Reference](https://code.visualstudio.com/api/references/theme-color)
265+
- [TextMate Scopes](https://macromates.com/manual/en/language_grammars)
266+
- [VSCode Extension API](https://code.visualstudio.com/api)

0 commit comments

Comments
 (0)