Setting the file. One moment.
Skill 02 · Content Modeling Best Practices
Subchapter 2.3
references/separation-of-concerns.mdMarkdown2 KBView on GitHub
The most important principle in structured content: separate what content IS from how it LOOKS.
When content is tied to presentation:
Model content based on meaning and purpose, not visual appearance.
BigHeroText → What if we want small heroes?
RedButton → What if brand colors change?
ThreeColumnLayout → What if mobile needs one column?
LeftSidebar → Position is a frontend concern
MobileImage → Device-specific content is fragileHeadline → The main message (render however)
CallToAction → An action we want users to take
Features → A list of things (columns decided by frontend)
RelatedContent → Content relationships (position by context)
Image → One image with responsive cropsAsk: “If we completely redesigned the site, would these field names still make sense?”
threeColumnFeatures → ❌ Fails (what if 2 columns?)features → ✅ Works (describes the content’s purpose: a list of product features)blueHighlightBox → ❌ Fails (what if we go purple?)callout → ✅ Works (describes the content’s role: an attention-grabbing aside)// ❌ Avoid presentation-focused names
defineField({ name: 'bigHeroText', type: 'string' })
defineField({ name: 'fontSize', type: 'number' })
defineField({ name: 'backgroundColor', type: 'color' })
// ✅ Use meaning-focused names
defineField({ name: 'headline', type: 'string' })
defineField({ name: 'emphasis', type: 'string', options: { list: ['standard', 'prominent'] } })
defineField({ name: 'tone', type: 'string', options: { list: ['neutral', 'warning', 'success'] } })The frontend translates tone: 'warning' to visual styles. Content stays semantic.