Skip to content

Commit b18bc6d

Browse files
diegochinediegochine
committed
Refactored AGENTS.md into separate "Repository Guidelines" and " Bespoke Template Design System Guidelines" docs
1 parent c892f1e commit b18bc6d

File tree

2 files changed

+522
-236
lines changed

2 files changed

+522
-236
lines changed

‎AGENTS.md‎

Lines changed: 88 additions & 236 deletions
Original file line numberDiff line numberDiff line change
@@ -1,88 +1,43 @@
1-
# BESPOKE GENERALIZED COMPONENTS - IMPLEMENTATION CONTEXT
1+
# Repository Guidelines
22

3-
This document provides precise implementation instructions for creating embedded applications using the Bespoke generalized components. Follow these instructions exactly to ensure consistency across all applications.
3+
This repository contains a template for building embedded applications using
4+
the Bespoke Simulation framework. For complete template documentation, see
5+
[BESPOKE-TEMPLATE.md](./BESPOKE-TEMPLATE.md).
46

5-
## REQUIRED FILES STRUCTURE
7+
## Overview
68

7-
Every application MUST include these files in the following order:
9+
This template provides:
10+
- CodeSignal Design System integration
11+
- Consistent layout components (header, sidebar, main content area)
12+
- Help modal system
13+
- Local development server with WebSocket support
14+
- Standardized file structure and naming conventions
815

9-
1. Design System CSS files (from design-system submodule)
10-
2. help-modal.js (help system)
11-
3. app.js (application logic)
12-
4. server.js (server)
16+
## Quick Start
1317

14-
## HTML TEMPLATE IMPLEMENTATION
18+
1. **Customize the HTML template** (`client/index.html`):
19+
- Replace `<!-- APP_TITLE -->` with your page title
20+
- Replace `<!-- APP_NAME -->` with your app name
21+
- Add your main content at `<!-- APP_SPECIFIC_MAIN_CONTENT -->`
22+
- Add app-specific CSS links at `<!-- APP_SPECIFIC_CSS -->`
23+
- Add app-specific JavaScript at `<!-- APP_SPECIFIC_SCRIPTS -->`
1524

16-
1. REPLACE the following placeholders in index.html EXACTLY as specified:
25+
2. **Create your application files**:
26+
- App-specific CSS (e.g., `my-app.css`)
27+
- App-specific JavaScript (e.g., `my-app.js`)
28+
- Help content (based on `help-content-template.html`)
1729

18-
a) `<!-- APP_TITLE -->`
19-
Replace with your application's page title
20-
Example: "Database Designer" or "Task Manager"
30+
3. **Start the development server**:
31+
```bash
32+
npm start
33+
```
34+
Server runs on `http://localhost:3000`
2135

22-
b) `<!-- APP_NAME -->`
23-
Replace with your application's display name (appears in header)
24-
Example: "Database Designer" or "Task Manager"
36+
## Key Conventions
2537

26-
c) `<!-- APP_SPECIFIC_MAIN_CONTENT -->`
27-
Add your application's main content area
28-
Example: `<div id="canvas"></div>` or `<div id="editor"></div>`
38+
### Status Messages
2939

30-
d) `<!-- APP_SPECIFIC_CSS -->`
31-
Add links to your application-specific CSS files
32-
Example: `<link rel="stylesheet" href="./my-app.css" />`
33-
34-
e) `<!-- APP_SPECIFIC_SCRIPTS -->`
35-
Add links to your application-specific JavaScript files
36-
Example: `<script src="./my-app-logic.js"></script>`
37-
38-
3. DO NOT modify the core structure (header, script loading order, etc.)
39-
40-
## CSS IMPLEMENTATION
41-
42-
1. INCLUDE the design-system CSS files in your HTML (already included in index.html template):
43-
- Foundations: colors, spacing, typography
44-
- Components: button, boxes, input, dropdown, icons, tags
45-
46-
2. USE design-system CSS custom properties for styling:
47-
- Colors: `--Colors-*` variables (see design-system/colors/README.md)
48-
- Spacing: `--UI-Spacing-*` variables (see design-system/spacing/README.md)
49-
- Typography: `--Fonts-*` variables (see design-system/typography/README.md)
50-
51-
3. USE design-system component classes:
52-
- Buttons: `.button`, `.button-primary`, `.button-secondary`, `.button-tertiary`, `.button-danger`
53-
- Boxes: `.box`, `.box.card` for card-style containers
54-
- Inputs: `.input` class for text/number inputs
55-
56-
4. FOR custom styling, create app-specific CSS files
57-
5. OVERRIDE design-system variables in your app-specific CSS if needed
58-
6. FOLLOW design-system naming conventions for consistency
59-
60-
## JAVASCRIPT IMPLEMENTATION
61-
62-
1. HELP MODAL SETUP:
63-
a) Create help content using help-content-template.html as reference
64-
b) Initialize HelpModal with:
65-
- triggerSelector: `'#btn-help'`
66-
- content: your help content (string or loaded from file)
67-
- theme: `'auto'`
68-
69-
2. STATUS MANAGEMENT:
70-
a) Use the provided setStatus() function for status updates
71-
b) Update status for: loading, saving, errors, user actions
72-
c) Keep status messages concise and informative
73-
74-
## ERROR HANDLING REQUIREMENTS
75-
76-
1. WRAP all async operations in try-catch blocks
77-
2. PROVIDE meaningful error messages to users
78-
3. LOG errors to console for debugging
79-
4. IMPLEMENT retry logic for network operations
80-
5. HANDLE localStorage quota exceeded errors
81-
6. VALIDATE data before saving operations
82-
83-
## STATUS MESSAGE CONVENTIONS
84-
85-
Use these EXACT status messages for consistency:
40+
Use these exact status messages for consistency:
8641

8742
- "Ready" - Application loaded successfully
8843
- "Loading..." - Data is being loaded
@@ -92,188 +47,85 @@ Use these EXACT status messages for consistency:
9247
- "Failed to load data" - Data loading failed
9348
- "Auto-save initialized" - Auto-save system started
9449

95-
## FILE NAMING CONVENTIONS
96-
97-
1. CSS files: kebab-case (e.g., my-app.css, task-manager.css)
98-
2. JavaScript files: kebab-case (e.g., my-app.js, task-manager.js)
99-
3. Data files: kebab-case (e.g., solution.json, initial-data.json)
100-
4. Image files: kebab-case (e.g., overview.png, help-icon.svg)
50+
### File Naming
10151

102-
---
52+
- CSS files: kebab-case (e.g., `my-app.css`)
53+
- JavaScript files: kebab-case (e.g., `my-app.js`)
54+
- Data files: kebab-case (e.g., `solution.json`)
55+
- Image files: kebab-case (e.g., `overview.png`)
10356

104-
# DESIGN SYSTEM USAGE GUIDELINES
57+
### Error Handling
10558

106-
This section explains how to use the design-system for embedded applications.
59+
- Wrap all async operations in try-catch blocks
60+
- Provide meaningful error messages to users
61+
- Log errors to console for debugging
62+
- Implement retry logic for network operations
63+
- Handle localStorage quota exceeded errors
64+
- Validate data before saving operations
10765

108-
## OVERVIEW
109-
The design-system provides reusable components and design tokens that can be embedded in any website. The design-system uses CSS custom properties and component classes for consistent styling.
66+
## Development Workflow
11067

111-
## BASIC USAGE
68+
### Build and Test
11269

113-
### 1. Include the Design System CSS
114-
The HTML template already includes all necessary design-system CSS files:
115-
- Foundations: colors, spacing, typography
116-
- Components: button, boxes, input, dropdown, icons, tags
70+
```bash
71+
# Start development server
72+
npm start
11773

118-
### 2. Use the Component Classes
119-
```html
120-
<header>
121-
<h1>My App</h1>
122-
<div id="status">Ready</div>
123-
<button class="button button-secondary">Help</button>
124-
</header>
125-
126-
<main>
127-
<aside>
128-
<section class="box card">
129-
<h2>Settings</h2>
130-
<form>
131-
<label>Name
132-
<input type="text" class="input" placeholder="Enter name" />
133-
</label>
134-
<button type="submit" class="button button-primary">Save</button>
135-
</form>
136-
</section>
137-
</aside>
138-
139-
<div>
140-
<!-- Main content -->
141-
</div>
142-
</main>
74+
# Development mode (same as start)
75+
npm run dev
14376
```
14477

145-
## COMPONENT REFERENCE
78+
### WebSocket Messaging
14679

147-
### LAYOUT COMPONENTS
80+
The server provides a `POST /message` endpoint for real-time messaging:
14881

149-
#### Header
150-
```html
151-
<header>
152-
<h1>App Title</h1>
153-
<div id="status">Status message</div>
154-
<button class="button button-secondary">Help</button>
155-
</header>
82+
```bash
83+
curl -X POST http://localhost:3000/message \
84+
-H "Content-Type: application/json" \
85+
-d '{"message": "Your message here"}'
15686
```
15787

158-
Note: Layout classes like `.header`, `.sidebar`, `.main-layout`, `.content-area` are not provided by the design-system. You may need to create custom layout styles or use semantic HTML with your own CSS.
159-
160-
#### Cards
161-
```html
162-
<section class="box card">
163-
<h2>Card Title</h2>
164-
<h3>Subtitle</h3>
165-
<p>Card content goes here</p>
166-
</section>
88+
This sends alerts to connected clients. Requires `ws` package:
89+
```bash
90+
npm install
16791
```
16892

169-
### FORM COMPONENTS
93+
## Template Documentation
17094

171-
#### Labels
172-
```html
173-
<!-- Vertical label -->
174-
<label>Field Name
175-
<input type="text" class="input" placeholder="Enter text" />
176-
</label>
177-
```
95+
For detailed information about:
96+
- Design System usage and components
97+
- CSS implementation guidelines
98+
- JavaScript API (HelpModal, status management)
99+
- Component reference and examples
100+
- Customization options
178101

179-
Note: The design-system does not provide specific label or form layout classes. Use semantic HTML and create custom styles if needed.
102+
See [BESPOKE-TEMPLATE.md](./BESPOKE-TEMPLATE.md).
180103

181-
#### Input Fields
182-
```html
183-
<!-- Text input (use .input class) -->
184-
<input type="text" class="input" placeholder="Enter text" />
104+
## Project Structure
185105

186-
<!-- Number input -->
187-
<input type="number" class="input" placeholder="Enter number" />
188106
```
189-
190-
Note: The design-system provides `.input` class for text and number inputs. For other form elements (select, textarea, checkbox, radio, toggle), you may need to create custom styles or use native HTML elements.
191-
192-
#### Buttons
193-
```html
194-
<!-- Default button -->
195-
<button class="button">Click Me</button>
196-
197-
<!-- Button variants -->
198-
<button class="button button-primary">Primary Action</button>
199-
<button class="button button-danger">Delete</button>
200-
<button class="button button-secondary">Secondary</button>
201-
<button class="button button-tertiary">Tertiary</button>
202-
203-
<!-- Button as link -->
204-
<a href="#" class="button button-primary">Link Button</a>
107+
client/
108+
├── index.html # Main HTML template
109+
├── app.js # Application logic
110+
├── bespoke-template.css # Template-specific styles
111+
├── help-modal.js # Help modal system
112+
├── help-content-template.html # Help content template
113+
└── design-system/ # CodeSignal Design System
114+
├── colors/
115+
├── spacing/
116+
├── typography/
117+
└── components/
118+
server.js # Development server
205119
```
206120

207-
### MODAL COMPONENTS
208-
209-
Note: The design-system does not provide modal components. The help-modal.js system creates modals dynamically. For custom modals, you may need to create your own modal styles or use a separate modal library.
210-
211-
## CUSTOMIZATION
212-
213-
### CSS Custom Properties
214-
You can override design-system CSS custom properties to customize the appearance:
215-
216-
```css
217-
:root {
218-
/* Override colors */
219-
--Colors-Base-Primary-700: #ff6b6b;
220-
--Colors-Base-Neutral-00: #f0f0f0;
221-
222-
/* Override spacing */
223-
--UI-Spacing-spacing-m: 1.5rem;
224-
225-
/* Override border radius */
226-
--UI-Radius-radius-m: 12px;
227-
}
228-
```
229-
230-
### Available Custom Properties
231-
232-
See the design-system documentation for complete variable lists:
233-
- **Colors**: See `design-system/colors/README.md` for all color variables
234-
- **Spacing**: See `design-system/spacing/README.md` for spacing and radius variables
235-
- **Typography**: See `design-system/typography/README.md` for typography variables
236-
- **Components**: Each component has its own variables (see component READMEs)
237-
238-
## THEME SUPPORT
239-
240-
### Automatic Dark Mode
241-
The design-system automatically detects the user's system preference and switches between light and dark themes using `@media (prefers-color-scheme: dark)`. No additional configuration is needed.
242-
243-
## INTEGRATION EXAMPLES
244-
245-
### Database Designer
246-
```html
247-
<header>
248-
<h1>DB Schema Designer</h1>
249-
<button id="btn-save" class="button button-primary">Save</button>
250-
<div id="status">Ready</div>
251-
<button id="btn-help" class="button button-secondary">Help</button>
252-
</header>
253-
254-
<main>
255-
<aside>
256-
<section class="box card">
257-
<h2>New Table</h2>
258-
<form>
259-
<label>Table name
260-
<input type="text" class="input" placeholder="users" />
261-
</label>
262-
<button type="submit" class="button button-primary">Add Table</button>
263-
</form>
264-
</section>
265-
</aside>
266-
267-
<div>
268-
<!-- Diagram area -->
269-
</div>
270-
</main>
271-
```
121+
## Notes for AI Agents
272122

273-
## BEST PRACTICES
123+
When working on applications built with this template:
274124

275-
1. **Use design-system components**: Use provided component classes (`.button`, `.box`, `.input`, etc.)
276-
2. **Use semantic HTML**: Combine with proper HTML elements for accessibility
277-
3. **Customize via CSS variables**: Override design-system variables in your app-specific CSS
278-
4. **Test in both themes**: Ensure your app works in light and dark modes
279-
5. **Refer to design-system docs**: Check `design-system/README.md` and component READMEs for available classes and variables
125+
1. **Always reference BESPOKE-TEMPLATE.md** for template-specific
126+
implementation details
127+
2. **Follow the conventions** listed above for status messages and file naming
128+
3. **Use Design System components** directly - see BESPOKE-TEMPLATE.md for
129+
component classes and usage
130+
4. **Maintain consistency** with the template's structure and patterns
131+
5. **Keep guidelines up to date** by editing this AGENTS.md file as the codebase evolves

0 commit comments

Comments
 (0)