Skip to content

Commit 93ccfca

Browse files
mavomenmavomen
committed
docs(agents): Update AGENTS.md
1 parent 6df29f2 commit 93ccfca

1 file changed

Lines changed: 181 additions & 105 deletions

File tree

‎AGENTS.md‎

Lines changed: 181 additions & 105 deletions
Original file line numberDiff line numberDiff line change
@@ -39,27 +39,87 @@ If the seed colors don't cover a semantic need (e.g., no green for `dragonGreen`
3939
- Are distinct enough from existing colors to be useful
4040

4141
### Palette Naming Convention
42-
Name palette entries semantically and thematically. Use names that reflect the theme's universe. Examples:
43-
- Kanagawa → `sumiInk0`, `dragonBlue`, `fujiWhite`
44-
- Cyberpunk → `neonPink`, `gridBlue`, `terminalGreen`
45-
- Desert → `sandstone`, `duskOrange`, `canyonRed`
42+
43+
The palette uses a **hybrid naming system** — two distinct groups with different naming rules:
44+
45+
#### Group 1 — Functional Scale Names (always lowercase_snake_case)
46+
Used for backgrounds, foregrounds, and alternate backgrounds. These are **fixed slot names** the system relies on:
47+
48+
```lua
49+
-- Backgrounds: darkest → lightest
50+
bg_darkest = "#......",
51+
bg_darker = "#......",
52+
bg_dark = "#......",
53+
bg_mid = "#......",
54+
bg_light = "#......",
55+
bg_lighter = "#......",
56+
bg_lightest = "#......",
57+
58+
-- Alternate backgrounds (for subtle variation / panels)
59+
bg_alt1 = "#......",
60+
bg_alt2 = "#......",
61+
bg_alt3 = "#......",
62+
bg_alt4 = "#......",
63+
64+
-- Foregrounds: lightest → darkest
65+
fg_lightest = "#......",
66+
fg_light = "#......",
67+
fg_mid = "#......",
68+
fg_dark = "#......",
69+
```
70+
71+
#### Group 2 — Thematic Proper Names (camelCase, theme-evocative)
72+
Used for all accent, vivid, and special colors. Names must **evoke the theme's identity** — not generic labels like `color1` or `accent_blue`:
73+
74+
```lua
75+
-- Examples from different universes:
76+
-- Crime / Noir theme:
77+
femmeRed = "#DC143C",
78+
lipstickRed = "#E63946",
79+
sapphireBlue = "#0F52BA",
80+
champagneGold = "#F7E7CE",
81+
emeraldHeist = "#50C878",
82+
seductionPink = "#FF69B4",
83+
amethystPurple = "#9966CC",
84+
85+
-- Kanagawa:
86+
dragonBlue = "#7E9CD8",
87+
fujiWhite = "#DCD7BA",
88+
dragonGreen = "#76946A",
89+
90+
-- Cyberpunk:
91+
neonPink = "#FF007F",
92+
terminalGreen = "#00FF41",
93+
gridBlue = "#00BFFF",
94+
```
95+
96+
Additionally, some themes add **thematic dark shades** as named entries (these complement the functional scale):
97+
```lua
98+
-- Named dark shades with thematic flavor:
99+
selinaBlack = "#1A0F14",
100+
velvetBlack = "#241A20",
101+
midnightSilk = "#1F151A",
102+
laceDark = "#2D1F26",
103+
```
46104

47105
### Fixed Required Slots
48-
Every palette **must** include these two named entries pointing to the darkest and lightest colors:
106+
Every palette **must** include these two entries pointing to the darkest bg and lightest fg:
49107
```lua
50-
bg_darkest = "#......", -- alias to your darkest bg color
51-
fg_lightest = "#......", -- alias to your lightest fg color
108+
bg_darkest = "#......", -- must be the darkest color in the palette
109+
fg_lightest = "#......", -- must be the lightest color in the palette
52110
```
53111

54112
### Recommended Palette Structure
55113
Aim to cover these semantic roles across your ~20 colors:
56114

57-
| Role | Count | Notes |
58-
|------------------|-------|--------------------------------------------|
59-
| Backgrounds | 6–8 | Darkest to lightest, for layering UI depth |
60-
| Foregrounds | 3–4 | Lightest to darkest, for text hierarchy |
61-
| Accent/Vivid | 5–7 | Syntax colors: red, blue, green, yellow, violet, aqua, orange, pink |
62-
| Special | 2–4 | Theme-specific decorative colors |
115+
| Role | Names | Count | Notes |
116+
|------------------------|--------------------|-------|----------------------------------------------|
117+
| Background scale | `bg_darkest` → `bg_lightest` | 5–7 | Ordered darkest to lightest |
118+
| Alternate backgrounds | `bg_alt1`–`bg_alt4` | 2–4 | Subtle variants for panels, splits |
119+
| Foreground scale | `fg_lightest` → `fg_dark` | 3–4 | Ordered lightest to darkest |
120+
| Named dark shades | camelCase | 2–4 | Thematic named entries for deeper bg layers |
121+
| Accent / Vivid | camelCase | 6–9 | Red, blue, green, yellow, violet, aqua, pink, orange, gold |
122+
| Special / Decorative | camelCase | 2–3 | Unique to the theme's identity |
63123

64124
---
65125

@@ -125,27 +185,43 @@ Produce a complete `.lua` file following this exact structure.
125185
local color = require("prismpunk.utils.color")
126186

127187
local palette = {
128-
-- Backgrounds (darkest → lightest)
129-
themeBg0 = "#......",
130-
themeBg1 = "#......",
131-
-- ... more bg layers
132-
133-
-- Foregrounds (lightest → darkest)
134-
themeFg0 = "#......",
135-
themeFg1 = "#......",
136-
-- ... more fg shades
137-
138-
-- Accent / Vivid Colors
139-
themeRed = "#......",
188+
-- Functional background scale (darkest → lightest)
189+
bg_darkest = "#......",
190+
bg_darker = "#......",
191+
bg_dark = "#......",
192+
bg_mid = "#......",
193+
bg_light = "#......",
194+
bg_lighter = "#......",
195+
bg_lightest = "#......",
196+
197+
-- Alternate backgrounds
198+
bg_alt1 = "#......",
199+
bg_alt2 = "#......",
200+
bg_alt3 = "#......",
201+
202+
-- Functional foreground scale (lightest → darkest)
203+
fg_lightest = "#......",
204+
fg_light = "#......",
205+
fg_mid = "#......",
206+
fg_dark = "#......",
207+
208+
-- Thematic named dark shades (camelCase, evoke the theme)
209+
themeBlack1 = "#......", -- rename to fit your theme, e.g. velvetBlack
210+
themeBlack2 = "#......",
211+
212+
-- Accent / Vivid colors (camelCase, thematic proper names)
213+
themeRed = "#......", -- e.g. crimsonBlade, femmeRed, neonRed
214+
themePink = "#......", -- e.g. seductionPink, sakuraPink
215+
themeOrange = "#......",
216+
themeYellow = "#......",
217+
themeGreen = "#......",
218+
themeAqua = "#......",
140219
themeBlue = "#......",
141-
-- ... more accents
142-
143-
-- Special / Decorative
144-
themeGlow = "#......",
220+
themeViolet = "#......",
145221

146-
-- Required aliases
147-
bg_darkest = "#......", -- must match your darkest bg
148-
fg_lightest = "#......", -- must match your lightest fg
222+
-- Special / Decorative (unique to this theme)
223+
themeGlow = "#......", -- e.g. champagneGold, edoGlow, neonFlare
224+
themeSpecial = "#......",
149225
}
150226

151227
local M = {}
@@ -200,67 +276,67 @@ M.get = function(opts, plt)
200276
#### `ui` — All UI element colors
201277
```lua
202278
ui = {
203-
fg = plt.themeFg0,
204-
fg_dim = plt.themeFg1,
205-
fg_dimmer = plt.themeFg2,
206-
fg_dark = plt.themeBg5,
207-
fg_reverse = plt.themeBg0,
208-
bg = plt.themeBg0,
209-
bg_dim = plt.themeBg0,
210-
bg_m1 = plt.themeBg1,
211-
bg_m2 = plt.themeBg2,
212-
bg_m3 = plt.themeBg3,
213-
bg_m4 = plt.themeBg4,
214-
bg_p1 = plt.themeBg2,
215-
bg_p2 = plt.themeBg3,
216-
bg_gutter = (opts.gutter ~= false) and plt.themeBg4 or "none",
217-
bg_cursorline = plt.themeBg3,
218-
bg_cursorline_alt = plt.themeBg4,
219-
cursorline = plt.themeBg3,
220-
bg_highlight = plt.themeBg4,
221-
bg_search = plt.themeGlow,
222-
bg_visual = plt.themeBg4,
223-
bg_statusline = plt.themeBg4,
224-
border = plt.themeBg0,
279+
fg = plt.fg_lightest,
280+
fg_dim = plt.fg_light,
281+
fg_dimmer = plt.fg_mid,
282+
fg_dark = plt.fg_dark,
283+
fg_reverse = plt.bg_darkest,
284+
bg = plt.bg_darkest,
285+
bg_dim = plt.bg_darkest,
286+
bg_m1 = plt.bg_darker,
287+
bg_m2 = plt.bg_dark,
288+
bg_m3 = plt.bg_mid,
289+
bg_m4 = plt.bg_light,
290+
bg_p1 = plt.bg_dark,
291+
bg_p2 = plt.bg_mid,
292+
bg_gutter = (opts.gutter ~= false) and plt.bg_light or "none",
293+
bg_cursorline = plt.bg_mid,
294+
bg_cursorline_alt = plt.bg_light,
295+
cursorline = plt.bg_mid,
296+
bg_highlight = plt.bg_light,
297+
bg_search = plt.themeGlow, -- thematic name
298+
bg_visual = plt.bg_light,
299+
bg_statusline = plt.bg_light,
300+
border = plt.bg_alt2,
225301
header1 = plt.themeYellow,
226302
header2 = plt.themeBlue,
227303
special = plt.themeSpecial,
228-
nontext = plt.themeBg5,
229-
whitespace = plt.themeFg2,
304+
nontext = plt.bg_lighter,
305+
whitespace = plt.fg_dark,
230306
win_separator = plt.themeViolet,
231-
indent = plt.themeBg4,
307+
indent = plt.bg_light,
232308
indent_scope = plt.themeBlue,
233309
picker = plt.themeViolet,
234310
yank = plt.themeGlow,
235311
mark = plt.themeRed,
236-
scrollbar = plt.themeBg5,
237-
selection = plt.themeBg4,
238-
line_nr = plt.themeFg2,
239-
line_nr_dim = plt.themeBg5,
240-
line_nr_active = plt.themeFg0,
312+
scrollbar = plt.bg_lighter,
313+
selection = plt.bg_light,
314+
line_nr = plt.fg_mid,
315+
line_nr_dim = plt.bg_lighter,
316+
line_nr_active = plt.fg_lightest,
241317
float = {
242-
fg = plt.themeFg1,
243-
bg = plt.themeBg3,
244-
fg_border = plt.themeBg5,
245-
bg_border = plt.themeBg3,
318+
fg = plt.fg_light,
319+
bg = plt.bg_mid,
320+
fg_border = plt.fg_dark,
321+
bg_border = plt.bg_mid,
246322
},
247323
pmenu = {
248-
fg = plt.themeFg0,
324+
fg = plt.fg_lightest,
249325
fg_sel = "none",
250-
fg_border = plt.themeBg5,
251-
bg = plt.themeBg4,
252-
bg_sel = plt.themeBg5,
253-
bg_border = plt.themeBg4,
254-
bg_sbar = plt.themeBg4,
255-
bg_thumb = plt.themeBg5,
326+
fg_border = plt.fg_dark,
327+
bg = plt.bg_light,
328+
bg_sel = plt.bg_lighter,
329+
bg_border = plt.bg_light,
330+
bg_sbar = plt.bg_light,
331+
bg_thumb = plt.bg_lighter,
256332
},
257333
tabline = {
258-
bg_inactive = plt.themeBg0,
259-
bg_selected = plt.themeBg2,
260-
bg_alternate = plt.themeBg1,
261-
bg = plt.themeBg0,
262-
fg_inactive = plt.themeFg2,
263-
fg_selected = plt.themeFg0,
334+
bg = plt.bg_darkest,
335+
bg_inactive = plt.bg_darkest,
336+
bg_selected = plt.bg_dark,
337+
bg_alternate = plt.bg_darker,
338+
fg_inactive = plt.fg_mid,
339+
fg_selected = plt.fg_lightest,
264340
fg_alternate = plt.themeYellow,
265341
indicator = plt.themeBlue,
266342
},
@@ -272,18 +348,18 @@ M.get = function(opts, plt)
272348
syn = {
273349
attribute = plt.themeYellow,
274350
boolean = plt.themeOrange,
275-
comment = plt.themeFg2,
351+
comment = plt.fg_mid, -- functional name: dimmed fg
276352
constant = plt.themeOrange,
277-
deprecated = plt.themeFg2,
353+
deprecated = plt.fg_dark,
278354
func = plt.themeBlue,
279-
identifier = plt.themeFg0,
355+
identifier = plt.fg_lightest,
280356
keyword = plt.themePink,
281357
method = plt.themeBlue,
282358
number = plt.themePink,
283359
operator = plt.themeRed,
284-
parameter = plt.themeFg2,
360+
parameter = plt.fg_mid,
285361
preproc = plt.themeViolet,
286-
punct = plt.themeFg2,
362+
punct = plt.fg_mid,
287363
regex = plt.themeYellow,
288364
special = plt.themeYellow,
289365
special2 = plt.themeViolet,
@@ -292,7 +368,7 @@ M.get = function(opts, plt)
292368
string = plt.themeGreen,
293369
symbol = plt.themeRed,
294370
type = plt.themeAqua,
295-
variable = plt.themeFg0,
371+
variable = plt.fg_lightest,
296372
},
297373
```
298374

@@ -337,22 +413,22 @@ M.get = function(opts, plt)
337413
#### `term` — Terminal colors (16 ANSI + optional indexed)
338414
```lua
339415
term = {
340-
black = plt.themeBg0,
416+
black = plt.bg_darkest,
341417
red = plt.themeRed,
342418
green = plt.themeGreen,
343419
yellow = plt.themeYellow,
344420
blue = plt.themeBlue,
345421
magenta = plt.themePink,
346422
cyan = plt.themeAqua,
347-
white = plt.themeFg1,
348-
black_bright = color(plt.themeBg0):brighten(0.6):to_hex(),
423+
white = plt.fg_light,
424+
black_bright = color(plt.bg_darkest):brighten(0.6):to_hex(),
349425
red_bright = color(plt.themeRed):brighten(0.2):to_hex(),
350426
green_bright = color(plt.themeGreen):brighten(0.1):to_hex(),
351427
yellow_bright = color(plt.themeYellow):brighten(0.2):to_hex(),
352428
blue_bright = color(plt.themeBlue):brighten(0.3):to_hex(),
353429
magenta_bright = color(plt.themePink):brighten(0.2):to_hex(),
354430
cyan_bright = color(plt.themeAqua):brighten(0.1):to_hex(),
355-
white_bright = color(plt.themeFg1):brighten(0.2):to_hex(),
431+
white_bright = color(plt.fg_light):brighten(0.2):to_hex(),
356432
-- Optional theme-specific indexed colors:
357433
indexed1 = plt.themeSpecial,
358434
indexed2 = plt.themeGlow,
@@ -370,22 +446,22 @@ return {
370446
author = "Author Name",
371447
description = "A concise description of the theme's aesthetic and inspiration.",
372448
base16 = {
373-
base00 = palette.themeBg0, -- Default Background
374-
base01 = palette.themeBg1, -- Lighter Background (used in status bars)
375-
base02 = palette.themeBg2, -- Selection Background
376-
base03 = palette.themeBg3, -- Comments, Invisibles
377-
base04 = palette.themeFg2, -- Dark Foreground (status bars)
378-
base05 = palette.themeFg1, -- Default Foreground
379-
base06 = palette.themeFg0, -- Light Foreground
380-
base07 = palette.themeFg0, -- Light Background
381-
base08 = palette.themeRed, -- Variables, XML Tags
382-
base09 = palette.themeOrange, -- Integers, Boolean
383-
base0A = palette.themeYellow, -- Classes, Markup Bold
384-
base0B = palette.themeGreen, -- Strings, Markup Code
385-
base0C = palette.themeAqua, -- Support, Regular Expressions
386-
base0D = palette.themeBlue, -- Functions, Methods
387-
base0E = palette.themeViolet, -- Keywords, Storage
388-
base0F = palette.themePink, -- Deprecated, Embedded Tags
449+
base00 = palette.bg_darkest, -- Default Background
450+
base01 = palette.bg_darker, -- Lighter Background (used in status bars)
451+
base02 = palette.bg_mid, -- Selection Background
452+
base03 = palette.bg_light, -- Comments, Invisibles
453+
base04 = palette.fg_dark, -- Dark Foreground (status bars)
454+
base05 = palette.fg_mid, -- Default Foreground
455+
base06 = palette.fg_light, -- Light Foreground
456+
base07 = palette.fg_lightest, -- Light Background
457+
base08 = palette.themeRed, -- Variables, XML Tags
458+
base09 = palette.themeOrange, -- Integers, Boolean
459+
base0A = palette.themeYellow, -- Classes, Markup Bold
460+
base0B = palette.themeGreen, -- Strings, Markup Code
461+
base0C = palette.themeAqua, -- Support, Regular Expressions
462+
base0D = palette.themeBlue, -- Functions, Methods
463+
base0E = palette.themeViolet, -- Keywords, Storage
464+
base0F = palette.themePink, -- Deprecated, Embedded Tags
389465
},
390466
palette = palette,
391467
get = M.get,

0 commit comments

Comments
 (0)