Spfx Enterprise Design Core | Skills Pool
Spfx Enterprise Design Core Core design guidance for SPFx web parts and extensions. Use for layout, hierarchy, commanding, text, empty states, and responsive behavior when building or reviewing SPFx UX.
Use this skill whenever you are designing or reviewing SPFx UX , not just a specific repo. It encodes Microsoft guidance for SharePoint web parts and extensions so any AI editor can propose consistent, accessible, performant UX.
Key MS references (for deeper detail – read only when needed):
快速安裝
Spfx Enterprise Design Core npx skills add sudharsank/spfx-enterprise-skills
星標 0
更新時間 2026年3月7日
職業
1. When to apply this skill Apply this guidance for any SPFx UI change , including:
New or significantly updated web parts
New SPFx extensions that introduce UI (Application/Field Customizers, Command Sets)
Changes to:
Layout, card structure, or grid behavior
Web part titles, descriptions, and commands
Empty, loading, error, and placeholder experiences
Responsive behavior across breakpoints
Information architecture (content groupings, levels, and flows)
Build/toolchain-only work (Heft/webpack, packaging)
Pure back-end/service work with no user-facing surface
2. Web part structure & levels Design SPFx web parts with clear levels and hierarchy:
Web part level
Title: clear, action- or outcome-oriented (e.g., "Permissions risk heatmap", not "PRH")
Description: 1–2 concise sentences answering: What does this do? and Why should I care?
Optional subtitle/context : scope or key filter (e.g., "Current site", "Last 30 days").
Section / region level
Group related content into visually distinct regions (cards, panels, tabs).
Each region should have a clear label (heading) and purpose.
Item level
Each row/card/tile must make sense on its own: label, primary metric/state, and key action.
Favor progressive disclosure : show high-value info first; move details into drill-ins.
Implementation snippet (React):
// Example web part root structure
return (
<section aria-label="Permissions risk heatmap" className={styles.webPartRoot}>
<header className={styles.header}>
<h2 className={styles.title}>Permissions risk heatmap</h2>
<p className={styles.description}>
Highlight sites and groups with the highest sharing and access risk.
</p>
{renderHeaderCommands()}
</header>
<main className={styles.content}>
{renderMainContent()}
</main>
</section>
);
3. Layout & responsive design Follow grid and responsive patterns from:
Use responsive layouts, not fixed widths
Prefer CSS grid / flex with min/max widths.
Avoid horizontal scroll for primary flows; let cards wrap.
Breakpoints (heuristics)
Small (< 480px) : single-column, stacked content; hide non-essential chrome.
Medium (480–1024px) : two-column cards, condensed table, fewer visible commands.
Large (> 1024px) : full grid/table, full command bar.
Do not rely on pixel-perfect design
Design for content resilience : longer labels, translated text, variable data.
.webPartRoot {
display: flex;
flex-direction: column;
}
.contentGrid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
gap: 12px;
}
@media (max-width: 480px) {
.contentGrid {
grid-template-columns: 1fr;
}
}
4. Web part titles, descriptions & UI text
Titles
Describe purpose and outcome , not implementation.
Avoid jargon and internal project names.
Good: "External sharing overview" vs. Bad: "ExtShareV2" .
Descriptions
1–2 sentences, present tense, user benefit first.
Example: "Track where external sharing is enabled and identify risky sites."
Labels & commands
Use verb-first labels for actions: "Filter", "Export", "Open details" .
Avoid using the same word for both state and action (e.g., "Sharing" as both a tab and a command).
Tone
Professional, direct, and neutral.
Avoid blame in error text: focus on resolution.
5. Commanding patterns
Primary vs secondary actions
One primary action (button) per main surface (e.g., "New", "Configure", "Fix issues").
Group secondary actions in menus when they clutter the surface.
Contextual commands
Row-level actions belong near the row (action icons or contextual menu).
Web-part-level actions belong in a header command bar.
Selection-aware behavior
Disable or hide commands that are invalid for the current selection.
Provide clear feedback when an action requires selection.
<CommandBar
items={[
{
key: 'newPolicy',
text: 'New policy',
iconProps: { iconName: 'Add' },
onClick: handleNewPolicy
},
{
key: 'export',
text: 'Export',
iconProps: { iconName: 'Download' },
onClick: handleExport
}
]}
/>
6. Placeholders, empty states, and fallbacks Design first-run and no-data experiences explicitly:
First-run / not configured
Show what the web part does , what is missing , and a clear next step .
Include a clear config action: "Open configuration" or link to settings pane.
No data (but configured)
Acknowledge the valid state: "No risky sites found in the last 30 days."
Offer a meaningful next step if possible: filter changes, documentation, or alternate view.
Fallback content
If some data is unavailable, show partial content instead of blocking everything.
if (!isConfigured) {
return (
<Placeholder
iconName="Settings"
iconText="Set up this web part"
description="Connect to a data source to see permissions risk for your sites."
buttonLabel="Open configuration"
onConfigure={openPropertyPane}
/>
);
}
if (!items?.length) {
return (
<EmptyState
title="No risky sites found"
description="We didn't find any sites that match your risk filters for this period."
/>
);
}
7. Accessibility basics (design side) Design decisions must support:
Keyboard and focus
All interactive elements must be reachable via Tab.
Visual focus indicator must be clearly visible against the background.
Semantics
Use semantic elements: <button>, <a>, <header>, <main>, <section>, <table>.
Use ARIA roles/labels only when necessary to supplement semantics.
Color & contrast
Do not rely on color alone to convey meaning (use icons/text as well).
Respect SharePoint theme tokens and ensure WCAG AA contrast.
Example focus treatment (SCSS):
.button {
border-radius: 2px;
&:focus-visible {
outline: 2px solid var(--focusBorder, #005a9e);
outline-offset: 2px;
}
}
Design choices affect performance:
Above-the-fold clarity
Show primary summary metrics or table quickly; defer expensive details.
Progressive rendering
Consider a lightweight summary view for large datasets, with explicit navigation to detail pages.
Config vs default behavior
Pick safe, performant defaults (shorter time windows, scoped data) and allow power users to expand.
9. How to use this skill in practice When an AI editor is asked to design or adjust SPFx UX:
Identify the surface: web part vs extension, first-run vs daily use.
Apply :
Section 2–3 for structure and layout.
Section 4–5 for titles, text, and commanding.
Section 6–7 for states and accessibility.
Propose concrete JSX/SCSS snippets that follow these patterns.
Check : Is the result understandable, accessible, responsive, and performant for an enterprise tenant?
02
2. Web part structure & levels