Skip to content

Commit 4d6955a

Browse files
utsengarutsengar
committed
docs(cms-best-practices): add detailed guidelines and examples for Webflow CMS architecture, best practices, and performance optimization
feat(cms-best-practices): introduce new collection patterns and relationship structures for improved scalability and maintainability style(cms-best-practices): refine field type selection and naming conventions for consistency and clarity docs(lumos-naming): add lumos naming system documentation and examples to the skills plugin feat(webflow-skills/skills/lumos-naming/SKILL.md): create new file for Lumos naming system documentation docs(webflow-skills/skills/flowkit-naming/SKILL.md): update Flowkit naming system documentation with responsive modifier guidelines docs(mast-naming): add comprehensive guide to Mast CSS naming system for Webflow projects
1 parent cbe7520 commit 4d6955a

File tree

5 files changed

+897
-0
lines changed

5 files changed

+897
-0
lines changed

‎plugins/webflow-skills/skills/client-first-naming/SKILL.md‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
---
2+
name: client-first-naming
3+
description: Apply Finsweet's Client-First CSS naming system in Webflow. Use when creating classes, auditing existing naming, or building new components following Client-First conventions.
4+
---
5+
6+
# Client-First Naming System
7+
8+
Help users apply Finsweet's Client-First CSS naming convention in Webflow projects.
9+
10+
## Instructions
11+
12+
1. **Identify the task**: Determine if user is creating new classes, auditing existing, or building components
13+
2. **Apply naming rules**: Follow Client-First structure for all class suggestions
14+
3. **Explain reasoning**: Help users understand why certain names follow the system
15+
16+
## Naming Structure
17+
18+
Client-First uses this pattern: `[identifier]_[element-name]`
19+
20+
### Core Identifiers
21+
22+
| Identifier | Purpose | Example |
23+
|------------|---------|---------|
24+
| `section_` | Page section wrappers | `section_hero`, `section_about` |
25+
| `container_` | Width-constraining containers | `container_large`, `container_small` |
26+
| `padding-global` | Global horizontal padding | `padding-global` |
27+
| `padding-section-` | Vertical section spacing | `padding-section-large` |
28+
| `component_` | Reusable component wrappers | `component_navbar`, `component_card` |
29+
| `[component]_` | Elements inside a component | `navbar_link`, `card_image` |
30+
| `button` | Button styles | `button`, `is-primary`, `is-large` |
31+
| `text-` | Typography utilities | `text-size-large`, `text-weight-bold` |
32+
| `heading-style-` | Heading variants | `heading-style-h1`, `heading-style-h2` |
33+
| `icon-` | Icon sizes/styles | `icon-1x1-small`, `icon-embed` |
34+
| `is-` | State/modifier classes | `is-active`, `is-dark`, `is-mobile` |
35+
| `hide-` | Responsive visibility | `hide-tablet`, `hide-mobile-portrait` |
36+
37+
### Breakpoint Names
38+
39+
- `desktop` (default, no suffix)
40+
- `tablet`
41+
- `mobile-landscape`
42+
- `mobile-portrait`
43+
44+
## Examples
45+
46+
**User prompt:**
47+
```
48+
I'm building a pricing section with cards. What classes should I use?
49+
```
50+
51+
**Response format:**
52+
```
53+
📐 Client-First Classes for Pricing Section
54+
55+
Section wrapper:
56+
└── section_pricing
57+
58+
Container:
59+
└── padding-global
60+
└── container_large
61+
└── padding-section-large
62+
63+
Content structure:
64+
├── pricing_header
65+
│ ├── pricing_label (use text-size-small)
66+
│ └── pricing_heading (use heading-style-h2)
67+
├── pricing_list (grid wrapper)
68+
└── pricing_item (individual card)
69+
70+
Card component:
71+
├── pricing_card
72+
│ ├── pricing_card-header
73+
│ ├── pricing_card-price
74+
│ ├── pricing_card-features
75+
│ └── pricing_card-button (use button is-primary)
76+
```
77+
78+
**User prompt:**
79+
```
80+
Audit these classes: hero-section, heroTitle, btn-primary, sec-about
81+
```
82+
83+
**Response format:**
84+
```
85+
📋 Client-First Audit
86+
87+
| Current | Issue | Suggested |
88+
|---------|-------|-----------|
89+
| hero-section | Missing identifier | section_hero |
90+
| heroTitle | camelCase, no identifier | hero_title + heading-style-h1 |
91+
| btn-primary | Non-standard prefix | button is-primary |
92+
| sec-about | Abbreviated identifier | section_about |
93+
94+
Summary: 4 classes need renaming for Client-First compliance.
95+
```
96+
97+
## Guidelines
98+
99+
- Always use lowercase with hyphens (not camelCase or underscores in element names)
100+
- Underscore `_` separates identifier from element name
101+
- Hyphen `-` separates words within element names
102+
- Component children inherit the component name: `navbar_link`, `navbar_logo`
103+
- Use utility classes for typography: `text-size-`, `text-weight-`, `text-color-`
104+
- States/modifiers use `is-` prefix as combo classes
105+
- Global styles (button, text utilities) don't need component prefix
106+
- Folder structure in Webflow: organize by identifier in the Style Panel
107+
108+
## Common Patterns
109+
110+
**Page section:**
111+
```
112+
section_[name]
113+
└── padding-global
114+
└── container_[size]
115+
└── padding-section-[size]
116+
└── [name]_component
117+
```
118+
119+
**Component:**
120+
```
121+
component_[name] (optional wrapper)
122+
└── [name]_wrapper
123+
├── [name]_content
124+
└── [name]_image-wrapper
125+
└── [name]_image
126+
```
127+
128+
**Button variations:**
129+
```
130+
button (base)
131+
button is-primary (filled)
132+
button is-secondary (outline)
133+
button is-small (size modifier)
134+
button is-icon (icon button)
135+
```
136+

‎plugins/webflow-skills/skills/cms-best-practices/SKILL.md‎

Lines changed: 242 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,242 @@
1+
---
2+
name: cms-best-practices
3+
description: Expert guidance on Webflow CMS architecture and best practices. Use when planning collections, setting up relationships, optimizing content structure, or troubleshooting CMS issues.
4+
---
5+
6+
# CMS Best Practices
7+
8+
Provide expert guidance on Webflow CMS architecture, relationships, and optimization.
9+
10+
## Instructions
11+
12+
1. **Understand the use case**: What content is being managed and how will it be displayed?
13+
2. **Recommend structure**: Suggest collections, fields, and relationships
14+
3. **Explain tradeoffs**: Help users understand limitations and workarounds
15+
4. **Optimize for scale**: Consider performance with large datasets
16+
17+
## Collection Architecture
18+
19+
### When to Use CMS vs Static
20+
21+
**Use CMS when:**
22+
- Content updates frequently
23+
- Multiple similar items (blog posts, products, team members)
24+
- Non-technical users need to edit content
25+
- Content needs filtering/sorting on the frontend
26+
- Same content appears on multiple pages
27+
28+
**Use Static when:**
29+
- Content rarely changes
30+
- Unique one-off sections
31+
- Complex custom layouts per item
32+
- No need for dynamic filtering
33+
34+
### Field Type Selection
35+
36+
| Content Type | Recommended Field | Notes |
37+
|--------------|-------------------|-------|
38+
| Short text (<256 chars) | Plain Text | Titles, names, slugs |
39+
| Long text (no formatting) | Plain Text (long) | Descriptions, excerpts |
40+
| Formatted content | Rich Text | Blog content, bios |
41+
| Single image | Image | Photos, thumbnails |
42+
| Multiple images | Multi-image | Galleries |
43+
| File downloads | File | PDFs, documents |
44+
| Yes/No values | Switch | Featured flags, visibility |
45+
| Single choice | Option | Status, category type |
46+
| Date/time | Date/Time | Publish dates, events |
47+
| Link to other item | Reference | Author → Post |
48+
| Link to multiple items | Multi-reference | Post → Tags |
49+
| External URL | Link | Social links, external resources |
50+
| Numeric values | Number | Prices, ratings, order |
51+
| Color values | Color | Theme colors, accents |
52+
53+
## Relationship Patterns
54+
55+
### One-to-Many (Reference Field)
56+
57+
**Example:** Posts → Author
58+
```
59+
Authors Collection:
60+
├── name (Text)
61+
├── bio (Rich Text)
62+
└── photo (Image)
63+
64+
Posts Collection:
65+
├── title (Text)
66+
├── content (Rich Text)
67+
└── author (Reference → Authors) ← Each post has ONE author
68+
```
69+
70+
**Display:** On post page, access `author.name`, `author.photo`
71+
72+
### Many-to-Many (Multi-Reference)
73+
74+
**Example:** Posts ↔ Tags
75+
```
76+
Tags Collection:
77+
├── name (Text)
78+
└── slug (Text)
79+
80+
Posts Collection:
81+
├── title (Text)
82+
├── content (Rich Text)
83+
└── tags (Multi-Reference → Tags) ← Each post has MANY tags
84+
```
85+
86+
**Limitations:**
87+
- Max 5 multi-reference fields per collection
88+
- Can only filter by ONE multi-reference value at a time
89+
- Cannot sort by referenced field values
90+
91+
### Nested Collections Pattern
92+
93+
For hierarchical content (Categories → Subcategories):
94+
```
95+
Categories Collection:
96+
├── name (Text)
97+
├── slug (Text)
98+
└── parent (Reference → Categories) ← Self-reference for hierarchy
99+
```
100+
101+
**Alternative:** Use Option field for simple categorization instead.
102+
103+
## Examples
104+
105+
**User prompt:**
106+
```
107+
I'm building a recipe site. How should I structure the CMS?
108+
```
109+
110+
**Response format:**
111+
```
112+
📐 CMS Architecture: Recipe Site
113+
114+
Collections needed:
115+
116+
1. Recipes (main content)
117+
├── name (Text, required)
118+
├── slug (Text, required)
119+
├── description (Plain Text)
120+
├── featured-image (Image)
121+
├── prep-time (Number) - minutes
122+
├── cook-time (Number) - minutes
123+
├── servings (Number)
124+
├── difficulty (Option: Easy, Medium, Hard)
125+
├── ingredients (Rich Text)
126+
├── instructions (Rich Text)
127+
├── author (Reference → Authors)
128+
├── category (Reference → Categories)
129+
├── tags (Multi-Reference → Tags)
130+
├── featured (Switch)
131+
└── publish-date (Date)
132+
133+
2. Categories
134+
├── name (Text)
135+
├── slug (Text)
136+
├── description (Plain Text)
137+
└── image (Image)
138+
139+
3. Tags
140+
├── name (Text)
141+
└── slug (Text)
142+
143+
4. Authors
144+
├── name (Text)
145+
├── bio (Rich Text)
146+
├── photo (Image)
147+
└── social-link (Link)
148+
149+
Relationships:
150+
- Recipe → Author (one-to-many)
151+
- Recipe → Category (one-to-many)
152+
- Recipe → Tags (many-to-many)
153+
154+
Recommended pages:
155+
- /recipes (Collection List with filters)
156+
- /recipes/[slug] (Collection Page)
157+
- /categories/[slug] (filtered recipe list)
158+
- /authors/[slug] (author profile + their recipes)
159+
```
160+
161+
**User prompt:**
162+
```
163+
My collection list is slow with 500+ items. How do I optimize?
164+
```
165+
166+
**Response format:**
167+
```
168+
⚡ CMS Performance Optimization
169+
170+
Current issue: Loading 500+ items impacts page speed.
171+
172+
Recommendations:
173+
174+
1. **Pagination**
175+
- Limit collection list to 12-20 items
176+
- Add "Load More" button or page navigation
177+
- Use Webflow's built-in pagination
178+
179+
2. **Lazy loading images**
180+
- Set images to load="lazy"
181+
- Use appropriate image sizes (not full resolution)
182+
183+
3. **Reduce reference field lookups**
184+
- Each reference field = additional query
185+
- Consider denormalizing (copy author name to post)
186+
- Only include reference fields you display
187+
188+
4. **Filter at collection level**
189+
- Don't load all items then hide with conditions
190+
- Use collection list filters to limit results
191+
192+
5. **Consider static for archives**
193+
- Recent 50 items: dynamic CMS
194+
- Older content: static archive pages
195+
196+
Quick wins:
197+
├── Limit to 20 items per page ✓
198+
├── Enable pagination ✓
199+
├── Remove unused reference bindings ✓
200+
└── Optimize image sizes ✓
201+
```
202+
203+
## Common Questions
204+
205+
### "How many collections can I have?"
206+
- Starter: 1 collection, 50 items
207+
- Basic: 2 collections, 200 items
208+
- CMS: 20 collections, 2,000 items
209+
- Business: 40 collections, 10,000 items
210+
- Enterprise: Custom limits
211+
212+
### "Can I filter by multiple tags?"
213+
Not directly. Workarounds:
214+
1. Create combined tag (e.g., "vegan-gluten-free")
215+
2. Use Finsweet CMS Filter for client-side filtering
216+
3. Create separate filtered collection lists
217+
218+
### "How do I reorder items?"
219+
1. Add a Number field called "order" or "sort-order"
220+
2. Set collection list to sort by that field
221+
3. Update numbers to change order
222+
223+
### "Can I schedule posts?"
224+
Yes! Use a Date field for "publish-date" and:
225+
1. Filter collection list: Publish Date < Today
226+
2. Items with future dates won't show
227+
228+
### "Should I use Rich Text or separate fields?"
229+
- **Rich Text:** Flexible content, blog posts, articles
230+
- **Separate fields:** Structured data you need to style individually
231+
232+
## Guidelines
233+
234+
- Plan collection structure before building pages
235+
- Use descriptive field names (not "text-1", "image-2")
236+
- Add help text to fields for content editors
237+
- Set required fields for essential data
238+
- Use Option fields instead of free text for controlled values
239+
- Create test items before building collection templates
240+
- Consider URL structure early (/blog/[slug] vs /posts/[slug])
241+
- Document your CMS structure for team members
242+

0 commit comments

Comments
 (0)