openAgent

1---
2description: use whenever you are styling a ui with css
3---
4 
5you are very good at writing clean maintainable css using modern techniques
6 
7css is structured like this
8 
9```css
10[data-page="home"] {
11  [data-component="header"] {
12    [data-slot="logo"] {
13    }
14  }
15}
16```
17 
18top level pages are scoped using `data-page`
19 
20pages can break down into components using `data-component`
21 
22components can break down into slots using `data-slot`
23 
24structure things so that this hierarchy is followed IN YOUR CSS - you should rarely need to
25nest components inside other components. you should NEVER nest components inside
26slots. you should NEVER nest slots inside other slots.
27 
28**IMPORTANT: This hierarchy rule applies to CSS structure, NOT JSX/DOM structure.**
29 
30The hierarchy in css file does NOT have to match the hierarchy in the dom - you
31can put components or slots at the same level in CSS even if one goes inside another in the DOM.
32 
33Your JSX can nest however makes semantic sense - components can be inside slots,
34slots can contain components, etc. The DOM structure should be whatever makes the most
35semantic and functional sense.
36 
37It is more important to follow the pages -> components -> slots structure IN YOUR CSS,
38while keeping your JSX/DOM structure logical and semantic.
39 
40use data attributes to represent different states of the component
41 
42```css
43[data-component="modal"] {
44  opacity: 0;
45 
46  &[data-state="open"] {
47    opacity: 1;
48  }
49}
50```
51 
52this will allow jsx to control the styling
53 
54avoid selectors that just target an element type like `> span` you should assign
55it a slot name. it's ok to do this sometimes where it makes sense semantically
56like targeting `li` elements in a list
57 
58in terms of file structure `./src/style/` contains all universal styling rules.
59these should not contain anything specific to a page
60 
61`./src/style/token` contains all the tokens used in the project
62 
63`./src/style/component` is for reusable components like buttons or inputs
64 
65page specific styles should go next to the page they are styling so
66`./src/routes/about.tsx` should have its styles in `./src/routes/about.css`
67 
68`about.css` should be scoped using `data-page="about"`
69 
70## Example of correct implementation
71 
72JSX can nest however makes sense semantically:
73 
74```jsx
75<div data-slot="left">
76  <div data-component="title">Section Title</div>
77  <div data-slot="content">Content here</div>
78</div>
79```
80 
81CSS maintains clean hierarchy regardless of DOM nesting:
82 
83```css
84[data-page="home"] {
85  [data-component="screenshots"] {
86    [data-slot="left"] {
87      /* styles */
88    }
89    [data-slot="content"] {
90      /* styles */
91    }
92  }
93 
94  [data-component="title"] {
95    /* can be at same level even though nested in DOM */
96  }
97}
98```
99 
100## Reusable Components
101 
102If a component is reused across multiple sections of the same page, define it at the page level:
103 
104```jsx
105<!-- Used in multiple places on the same page -->
106<section data-component="install">
107  <div data-component="method">
108    <h3 data-component="title">npm</h3>
109  </div>
110  <div data-component="method">
111    <h3 data-component="title">bun</h3>
112  </div>
113</section>
114 
115<section data-component="screenshots">
116  <div data-slot="left">
117    <div data-component="title">Screenshot Title</div>
118  </div>
119</section>
120```
121 
122```css
123[data-page="home"] {
124  /* Reusable title component defined at page level since it's used in multiple components */
125  [data-component="title"] {
126    text-transform: uppercase;
127    font-weight: 400;
128  }
129 
130  [data-component="install"] {
131    /* install-specific styles */
132  }
133 
134  [data-component="screenshots"] {
135    /* screenshots-specific styles */
136  }
137}
138```
139 
140This is correct because the `title` component has consistent styling and behavior across the page.
141 
142## Key Clarifications
143 
1441. **JSX Nesting is Flexible**: Components can be nested inside slots, slots can contain components - whatever makes semantic sense
1452. **CSS Hierarchy is Strict**: Follow pages → components → slots structure in CSS
1463. **Reusable Components**: Define at the appropriate level where they're shared (page level if used across the page, component level if only used within that component)
1474. **DOM vs CSS Structure**: These don't need to match - optimize each for its purpose
148 
149See ./src/routes/index.css and ./src/routes/index.tsx for a complete example.
150