CSS GUIDELINES · Wix App · wix/skills · Skills Docs

CSS GUIDELINES · Wix App · wix/skills · Skills Docs

Element type	className	Why
Named part	`classNames('profile-card-heading', styles.heading)`	Global string → zeroConfig creates an editor element; module class → applies the component’s own CSS
Non-part (layout/structural)	`styles.contentWrapper`	Module class only — invisible to zeroConfig, no spurious editor element created

import classNames from 'classnames';
import styles from './ProfileCard.module.css';

// ✅ Root: global string + module class + consumer className
// (a <div> here only because this component lays out several sibling parts)
<div className={classNames(className, 'profile-card', styles.root)} id={id}>

  {/* ✅ Named part: prefixed global string + short module class */}
  <h2 className={classNames('profile-card-heading', styles.heading)}>{heading}</h2>

  {/* ✅ Named part: interactive elements always get both classes */}
  <button type="button" className={classNames('profile-card-cta', styles.cta)}>
    {ctaLabel}
  </button>

  {/* ✅ Non-part layout wrapper: module class only */}
  <div className={styles.contentWrapper}>
    <span className={classNames('profile-card-label', styles.label)}>{label}</span>
  </div>
</div>

// ✅ Internal sub-components — same pattern on part slots
<CardHeader className={classNames('profile-card-header', styles.header)}>
  <CardTitle className={classNames('profile-card-title', styles.title)}>{title}</CardTitle>
</CardHeader>

// ✅ The <button> is the root: unprefixed global string, no elementProps entry
<button
  type="button"
  id={id}
  dir={direction}
  className={classNames('like-button', styles.root, className, styles.fallbackDirection)}
>
  {label}

  {/* ✅ Decoration: module class only, out of the a11y tree, not a part */}
  <span className={styles.burst} aria-hidden="true" />
</button>

/* ✅ Do: Single-class selector — unambiguous mapping to an editor control */
.profile-card {
}
.title {
}
.content {
}

/* ❌ Compound selector — rule applies only when both classes match the same element */
.profile-card.featured {
}

/* ❌ Descendant selector — rule depends on ancestor structure */
.profile-card .title {
}

/* ❌ Child combinator — rule depends on direct parent */
.profile-card > .content {
}

/* ❌ Sibling combinator — rule depends on a sibling element */
.title + .subtitle {
}

/* ❌ CSS nesting — compiles to a descendant selector */
.profile-card {
  & .title {
    color: black;
  }
}

/* ✅ Do: border-box — outer size stays stable while the editor tunes padding and border */
.profile-card,
.title,
.button {
  box-sizing: border-box;
}

/* ❌ content-box — outer size grows when the editor adjusts padding or border */
.profile-card {
  box-sizing: content-box; /* the default — don't rely on it */
}

/* ✅ Do: Container-driven sizing — adapts to the slot, not the viewport */
.card-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
  gap: clamp(1rem, 2.5vw, 2rem);
}

/* ❌ Viewport breakpoint — fights the editor's responsiveness model */
@media (max-width: 768px) {
  .card-grid {
    grid-template-columns: 1fr;
  }
}

/* ✅ Do: Inline logical properties — flip automatically in RTL */
.profile-card {
  padding-inline: 24px;
  margin-inline-start: 8px;
  border-inline-start: 4px solid currentColor;
}

/* ❌ Don't: Physical left/right — stays locked in RTL and breaks the layout */
.profile-card {
  padding-left: 24px;
  padding-right: 24px;
  margin-left: 8px;
  border-left: 4px solid currentColor;
}

/* ✅ Do: Block axis stays physical — top/bottom don't flip with direction */
.banner {
  position: sticky;
  top: 0;
  padding-block: 12px;
}

/* ✅ Do: Root declares --display only — platform applies it, editor can override */
.profile-card {
  --display: flex;
}

/* ❌ Don't: Root sets display directly — competes with the platform override */
.profile-card {
  --display: flex;
  display: var(--display);
}

/* ✅ Do: Inner elements set display normally — the --display rule is root-only */
.header {
  display: flex;
  align-items: center;
}

/* ✅ Do: Single column — stacked content (profile card, pricing card, CTA block) */
.profile-card {
  --display: flex;
  flex-direction: column;
  align-items: center;
  text-align: center;
  gap: 1rem;
  padding: clamp(1rem, 3vw, 2rem);
}

/* ✅ Do: Two-column split — media + text pair (testimonial, feature row, media card) */
.media-card {
  --display: grid;
  grid-template-columns: 1fr 1fr;
  gap: clamp(1rem, 3vw, 2rem);
  align-items: center;
}

/* ✅ Do: Multi-column grid — list of children (product list, testimonial list, gallery) */
.testimonial-list {
  --display: grid;
  grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
  gap: clamp(1rem, 2.5vw, 2rem);
}

/* ✅ Do: Inline row — fixed controls on edges, growing center
   (numeric stepper, search bar, toolbar, split button, pagination).
   Pair with stretch-chain rules: controls flex: 0 0 auto,
   center area flex: 1; min-width: 0. */
.numeric-stepper {
  --display: flex;
  flex-direction: row;
  align-items: center;
}

/* ❌ Don't: Unnecessary variable — value isn't interpolated anywhere */
.profile-card {
  --gap: 16px;
  gap: var(--gap);
}

/* ✅ Do: Literal value — nothing to interpolate */
.profile-card {
  gap: 16px;
}

/* ✅ Do: Variable required — value is consumed inside repeat() */
.card-grid {
  --columns: 3;
  grid-template-columns: repeat(var(--columns), 1fr);
}

// ❌ Inline style — invisible to zeroConfig, no editor control
<div className="profile-card" style={{ padding: 20, borderRadius: 8 }} />

// ✅ Do: Defaults in CSS — surfaced to the editor as controls
<div className="profile-card" />

/* ✅ Do: Defaults belong in CSS so the editor can surface them */
.profile-card {
  padding: 20px;
  border-radius: 8px;
  background: #ffffff; /* Use `background`, never `background-color` — the schema key is "background"; zeroConfig can't match "background-color" so the default is lost in the design panel */
}

Property	Guidance
`border-radius`	8–12 px containers, `50%` for controls and interactive groups (buttons, pills, input rows)
`box-shadow`	Prefer soft, diffused shadows over hard borders (e.g. `0 2px 8px rgba(0,0,0,0.06), 0 0 1px rgba(0,0,0,0.08)`)
Spacing	8–16 px inside controls, 16–32 px for containers. Avoid cramped layouts
Typography	Body ≥ 16 px, labels ≥ 14 px, headings larger. `font-weight: 500`–`600`
Palette	Root background transparent (blends with page). Use subtle fills (`#f1f5f9`/`#e2e8f0`) on inner controls only (buttons, input areas, pill containers). Text `#1e293b`/`#334155`, borders `#e2e8f0`. `#475569` for large/secondary text only
Accent	Use a muted accent color (e.g. `#6366f1`, `#7c83db`) sparingly on interactive icons, active indicators, and primary actions — just enough to signal interactivity without dominating
Contrast	WCAG AA minimum: 4.5:1 body text, 3:1 large text / UI controls
Hierarchy	Interactive elements visually distinct from static via weight, fill, or elevation
Touch targets	Interactive elements ≥ 44×44 px

/* ❌ Don't: decorative transition with no functional reason */
.button {
  transition: background-color 0.2s ease;
}

/* ❌ Don't: transition: all — animates every property the editor touches */
.button {
  transition: all 0.2s ease;
}

/* ❌ Don't: implicit all — duration-only shorthand resolves to transition-property: all */
.button {
  transition: 0.2s ease;
}

/* ✅ Do: Functional transition with specific properties named (e.g. accordion expand) */
.panel {
  transition: height 0.2s ease;
}