{"id":19407,"plugin_id":"plugins_6a986dc5b2d88191aa3fbe81033fb978","kind":"skill","collection_source":null,"comparison_source":null,"observed_at":"2026-09-30T23:15:33.134Z","digest":"3d751129c3be2194ba041be29aae3c5d61f54e9290d33539db6c1bb4ffe7a57a","against":null,"payload":{"description":"Best practices for experience modeling in Uniform — designing component definitions with well-chosen parameters, slots, editors, and naming, deciding between slots and parameters, blocks and slots, content-agnostic and content-specific components, choosing component granularity (atomic building blocks vs pre-composed components), and using component and composition patterns well (overrides, pattern data resources, slot sections, localization). Use when creating or updating Uniform component definitions or patterns, mapping code components (React, etc.) or a design system to Uniform components, or reviewing an existing component library for best-practice violations.","included_files":[{"relative_path":"agents/openai.yaml","size_in_bytes":199},{"relative_path":"references/component-definitions.md","size_in_bytes":2160},{"relative_path":"references/component-granularity.md","size_in_bytes":7799},{"relative_path":"references/component-naming.md","size_in_bytes":5739},{"relative_path":"references/component-scope.md","size_in_bytes":3067},{"relative_path":"references/parameters.md","size_in_bytes":10182},{"relative_path":"references/patterns.md","size_in_bytes":6244},{"relative_path":"references/review-checklist.md","size_in_bytes":7090},{"relative_path":"references/slots.md","size_in_bytes":11379}],"name":"uniform-experience-modeling","skill_md_contents":"---\nname: uniform-experience-modeling\ndescription: Best practices for experience modeling in Uniform — designing component definitions with well-chosen parameters, slots, editors, and naming, deciding between slots and parameters, blocks and slots, content-agnostic and content-specific components, choosing component granularity (atomic building blocks vs pre-composed components), and using component and composition patterns well (overrides, pattern data resources, slot sections, localization). Use when creating or updating Uniform component definitions or patterns, mapping code components (React, etc.) or a design system to Uniform components, or reviewing an existing component library for best-practice violations.\nlicense: MIT\n---\n\n# Uniform experience modeling\n\nExperience modeling is the process of building Uniform component definitions that represent the experience layer of a digital product: how content is displayed and how authors compose it. It contrasts with content modeling, which defines display-agnostic structured content (content types and entries). This skill encodes best practices for building component sets that are easy to author, easy to maintain, and map cleanly to code components.\n\n## Key principles\n\n### Components map to code components\n\nA Uniform component typically maps to a frontend code component. Parameters map to props; slots map to children or child-component props. Not every prop needs to be exposed — hardcode props that editors should not manage. Align parameter public IDs and types with the corresponding props to avoid mapping logic.\n\n### Choose the right component granularity\n\nComponents correlate strongly to the design system rendering the experience, and atomic design is a useful lens: atoms and molecules map to component definitions (or parameters — not every design-system component needs a Uniform component), organisms to definitions plus component patterns, templates to composition patterns, pages to compositions. Balance granular atomic and layout components (flexible, but shifts design decisions, design consistency, and responsive handling to editors) against pre-composed components and patterns (easier, more guard rails); both can coexist, with granular components reserved for exceptions and experimentation.\n\n### Design for editors first\n\nNames, help text, grouping, and editor controls exist for non-technical authors. Use non-technical names, write help text only when the purpose isn't obvious, group related parameters, collapse advanced settings, and pick the editor control (radio, segmented control, slider, switch, checkboxes) that matches how authors think about the setting.\n\n### Restrict slots deliberately\n\nNever enable the allow-all-components toggle on a slot. Allow only the components and patterns that make sense, plus the built-in Personalization and A/B Test components where optimization is expected, and the Loop component where children are rendered dynamically from data. An explicit allow-list may still be wide for granular setups — what to avoid is the allow-all toggle, not a long list.\n\n### Prefer slots over parameter groups and blocks for nested UI\n\nSlots keep nested elements flexible: extensible, personalizable, A/B testable, and reusable via patterns. Use parameter groups when simplicity matters more, and blocks only for non-visual structured data. When requirements are unclear, default to a restricted slot.\n\n### Keep composition parameters for global page data\n\nReserve composition parameters for global, page-level data (e.g. SEO/OpenGraph metadata); experience content belongs in components in the composition's content slot.\n\n### Keep components content-agnostic\n\nPrefer \"Card\" over \"Recipe Card\" — the component is a display container. Create content-specific variations with component patterns — either static (fixed, reused content) or connected to a data resource that wires entry fields to the base component's parameters. Only create content-specific components for core domain objects or use-case-specific behavior.\n\n### Use patterns deliberately\n\nA pattern reuses exact content (static), a preset configuration, or a connection to data — choose which intent it serves. Override settings are the governance dial: lock what must stay consistent, open only what instances legitimately vary, and reserve extension points with restricted slot sections.\n\n### Validate sparingly\n\nKeep validations on components limited to essential parameters. Strict validation belongs on content types, where data integrity matters more than authoring speed.\n\n## Resources\n\nSee `references/` for detailed guidance:\n- [Component definitions](references/component-definitions.md) — Component metadata, descriptions as AI guidance, display variants, mapping from code components\n- [Component naming](references/component-naming.md) — A method for choosing structural (not content-based) names, deferring to the existing design system, layout-qualifier variants, and child component naming conventions\n- [Component granularity](references/component-granularity.md) — Atomic design as a lens, classifying design-system elements, layout components, granular vs pre-composed balance\n- [Parameters](references/parameters.md) — Naming, type matching, help text and guidance, localization, grouping, editors, validations, display name\n- [Slots](references/slots.md) — Single vs multiple slots, slot naming, restricting slots, optimization and Loop components, slots vs parameter groups, composition parameters vs content slots, blocks vs slots\n- [Component scope](references/component-scope.md) — Content-agnostic vs content-specific components, patterns for content-specific variations\n- [Patterns](references/patterns.md) — Pattern strategy, overrides, pattern data resources, slot sections, editions, localization\n- [Review checklist](references/review-checklist.md) — Audit workflow and checklist for reviewing an existing component library\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}