@buffercreations/levelsui 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (116) hide show
  1. package/01. Elements/.gitkeep +0 -0
  2. package/01. Elements/actions/controls/button/api.json +106 -0
  3. package/01. Elements/actions/controls/button/button.definition.json +38 -0
  4. package/01. Elements/actions/controls/button/button.scss +80 -0
  5. package/01. Elements/actions/controls/button/docs.md +41 -0
  6. package/01. Elements/actions/controls/button/examples/contexts/code.html +3 -0
  7. package/01. Elements/actions/controls/button/examples/contexts/preview.html +3 -0
  8. package/01. Elements/actions/controls/button/examples/icons/code.html +6 -0
  9. package/01. Elements/actions/controls/button/examples/icons/preview.html +5 -0
  10. package/01. Elements/actions/controls/button/examples/index.json +51 -0
  11. package/01. Elements/actions/controls/button/examples/links/code.html +1 -0
  12. package/01. Elements/actions/controls/button/examples/links/preview.html +3 -0
  13. package/01. Elements/actions/controls/button/examples/native-default/code.html +9 -0
  14. package/01. Elements/actions/controls/button/examples/native-default/preview.html +9 -0
  15. package/01. Elements/actions/controls/button/examples/sizes/code.html +1 -0
  16. package/01. Elements/actions/controls/button/examples/sizes/preview.html +7 -0
  17. package/01. Elements/actions/controls/button/examples/states/code.html +1 -0
  18. package/01. Elements/actions/controls/button/examples/states/preview.html +5 -0
  19. package/01. Elements/actions/controls/button/examples/treatments/code.html +1 -0
  20. package/01. Elements/actions/controls/button/examples/treatments/preview.html +5 -0
  21. package/01. Elements/media/identity/avatar/api.json +126 -0
  22. package/01. Elements/media/identity/avatar/avatar.definition.json +38 -0
  23. package/01. Elements/media/identity/avatar/avatar.scss +80 -0
  24. package/01. Elements/media/identity/avatar/docs.md +64 -0
  25. package/01. Elements/media/identity/avatar/examples/badges/code.html +10 -0
  26. package/01. Elements/media/identity/avatar/examples/badges/preview.html +29 -0
  27. package/01. Elements/media/identity/avatar/examples/fallbacks/code.html +5 -0
  28. package/01. Elements/media/identity/avatar/examples/fallbacks/preview.html +23 -0
  29. package/01. Elements/media/identity/avatar/examples/index.json +37 -0
  30. package/01. Elements/media/identity/avatar/examples/presence/code.html +6 -0
  31. package/01. Elements/media/identity/avatar/examples/presence/preview.html +26 -0
  32. package/01. Elements/media/identity/avatar/examples/shapes/code.html +5 -0
  33. package/01. Elements/media/identity/avatar/examples/shapes/preview.html +17 -0
  34. package/01. Elements/media/identity/avatar/examples/sizes/code.html +5 -0
  35. package/01. Elements/media/identity/avatar/examples/sizes/preview.html +32 -0
  36. package/02. Layouts/.gitkeep +0 -0
  37. package/02. Layouts/UTILITY-RECIPES.md +55 -0
  38. package/02. Layouts/application/app-shell/api.json +46 -0
  39. package/02. Layouts/application/app-shell/app-shell.definition.json +25 -0
  40. package/02. Layouts/application/app-shell/app-shell.scss +68 -0
  41. package/02. Layouts/application/app-shell/docs.md +31 -0
  42. package/02. Layouts/application/app-shell/examples/basic/code.html +17 -0
  43. package/02. Layouts/application/app-shell/examples/basic/preview.html +17 -0
  44. package/02. Layouts/application/app-shell/examples/collapsed/code.html +17 -0
  45. package/02. Layouts/application/app-shell/examples/collapsed/preview.html +17 -0
  46. package/02. Layouts/application/app-shell/examples/hidden/code.html +17 -0
  47. package/02. Layouts/application/app-shell/examples/hidden/preview.html +17 -0
  48. package/02. Layouts/application/app-shell/examples/index.json +23 -0
  49. package/02. Layouts/composition/stack/api.json +1 -0
  50. package/02. Layouts/composition/stack/docs.md +5 -0
  51. package/02. Layouts/composition/stack/examples/basic/code.html +4 -0
  52. package/02. Layouts/composition/stack/examples/basic/preview.html +4 -0
  53. package/02. Layouts/composition/stack/examples/index.json +1 -0
  54. package/02. Layouts/composition/stack/stack.definition.json +7 -0
  55. package/02. Layouts/composition/stack/stack.html +4 -0
  56. package/02. Layouts/content/grid/api.json +23 -0
  57. package/02. Layouts/content/grid/docs.md +19 -0
  58. package/02. Layouts/content/grid/examples/basic/code.html +5 -0
  59. package/02. Layouts/content/grid/examples/basic/preview.html +5 -0
  60. package/02. Layouts/content/grid/examples/index.json +9 -0
  61. package/02. Layouts/content/grid/grid.definition.json +25 -0
  62. package/02. Layouts/content/grid/grid.scss +5 -0
  63. package/02. Layouts/content/split/api.json +23 -0
  64. package/02. Layouts/content/split/docs.md +18 -0
  65. package/02. Layouts/content/split/examples/basic/code.html +4 -0
  66. package/02. Layouts/content/split/examples/basic/preview.html +4 -0
  67. package/02. Layouts/content/split/examples/index.json +9 -0
  68. package/02. Layouts/content/split/split.definition.json +25 -0
  69. package/02. Layouts/content/split/split.scss +7 -0
  70. package/02. Layouts/primitives/overlay/api.json +23 -0
  71. package/02. Layouts/primitives/overlay/docs.md +19 -0
  72. package/02. Layouts/primitives/overlay/examples/basic/code.html +5 -0
  73. package/02. Layouts/primitives/overlay/examples/basic/preview.html +5 -0
  74. package/02. Layouts/primitives/overlay/examples/index.json +9 -0
  75. package/02. Layouts/primitives/overlay/overlay.definition.json +25 -0
  76. package/02. Layouts/primitives/overlay/overlay.scss +4 -0
  77. package/02. Layouts/sections/section/api.json +23 -0
  78. package/02. Layouts/sections/section/docs.md +19 -0
  79. package/02. Layouts/sections/section/examples/basic/code.html +5 -0
  80. package/02. Layouts/sections/section/examples/basic/preview.html +5 -0
  81. package/02. Layouts/sections/section/examples/index.json +9 -0
  82. package/02. Layouts/sections/section/section.definition.json +25 -0
  83. package/02. Layouts/sections/section/section.scss +4 -0
  84. package/02. Layouts/sections/sidebar/api.json +23 -0
  85. package/02. Layouts/sections/sidebar/docs.md +18 -0
  86. package/02. Layouts/sections/sidebar/examples/basic/code.html +4 -0
  87. package/02. Layouts/sections/sidebar/examples/basic/preview.html +4 -0
  88. package/02. Layouts/sections/sidebar/examples/index.json +9 -0
  89. package/02. Layouts/sections/sidebar/sidebar.definition.json +25 -0
  90. package/02. Layouts/sections/sidebar/sidebar.scss +7 -0
  91. package/03. Components/.gitkeep +0 -0
  92. package/04. Templates/.gitkeep +0 -0
  93. package/05. Pages/.gitkeep +0 -0
  94. package/LICENSE +17 -0
  95. package/README.md +29 -2
  96. package/dist/components/app-shell.css +95 -0
  97. package/dist/components/avatar.css +232 -0
  98. package/dist/components/button.css +150 -0
  99. package/dist/components/grid.css +22 -0
  100. package/dist/components/overlay.css +17 -0
  101. package/dist/components/section.css +14 -0
  102. package/dist/components/sidebar.css +22 -0
  103. package/dist/components/split.css +22 -0
  104. package/package.json +48 -4
  105. package/schemas/reusable-ui.schema.json +351 -0
  106. package/tooling/cli/build.mjs +82 -0
  107. package/tooling/cli/cli.mjs +56 -0
  108. package/tooling/cli/migrate.mjs +57 -0
  109. package/tooling/cli/project.mjs +261 -0
  110. package/tooling/cli/registry-location.mjs +32 -0
  111. package/tooling/cli/registry.mjs +3 -0
  112. package/tooling/registry/definitions.mjs +69 -0
  113. package/tooling/registry/index.mjs +3 -0
  114. package/tooling/registry/paths.mjs +15 -0
  115. package/tools/build-css.mjs +75 -0
  116. package/tools/validate.mjs +6 -0
@@ -0,0 +1,80 @@
1
+ /* BufferCore — Level 02 / Avatar. Pure CSS; no JS dependency. */
2
+ .bce-avatar {
3
+ --bce-avatar-size: var(--bc-size-ui-40);
4
+ --bce-avatar-radius: var(--bc-radius-full);
5
+ --bce-avatar-badge-size: var(--bc-size-ui-16);
6
+ --bce-avatar-initials-size: var(--bc-type-label-3-font-size);
7
+ position: relative;
8
+ display: inline-grid;
9
+ box-sizing: border-box;
10
+ flex: none;
11
+ width: var(--bce-avatar-size);
12
+ height: var(--bce-avatar-size);
13
+ place-items: center;
14
+ vertical-align: middle;
15
+ isolation: isolate;
16
+ color: var(--bc-color-text-context-strong);
17
+ }
18
+ .bce-avatar__face {
19
+ display: grid;
20
+ width: 100%;
21
+ height: 100%;
22
+ min-width: 0;
23
+ min-height: 0;
24
+ place-items: center;
25
+ overflow: hidden;
26
+ border-radius: var(--bce-avatar-radius);
27
+ background: var(--bc-color-fill-context-subtle);
28
+ color: var(--bc-color-text-context-strong);
29
+ }
30
+ .bce-avatar__image { display:block; width:100%; height:100%; object-fit:cover; }
31
+ .bce-avatar__fallback { display: none; width:100%; height:100%; place-items:center; text-align:center; font-family: var(--bc-type-label-3-font-family); font-weight: var(--bc-type-weight-600); font-size: var(--bce-avatar-initials-size); line-height: 1; }
32
+ .bce-avatar__fallback svg { display:block; width:52%; height:52%; fill:none; stroke:currentColor; stroke-width:1.75; stroke-linecap:round; stroke-linejoin:round; }
33
+ /* The fallback is visible when markup has no image or the application marks a failed image. */
34
+ .bce-avatar:not(:has(.bce-avatar__image)) .bce-avatar__fallback,
35
+ .bce-avatar[data-image-error="true"] .bce-avatar__fallback { display:grid; }
36
+ .bce-avatar[data-image-error="true"] .bce-avatar__image { display:none; }
37
+ /* Named size scale. Physical dimensions remain Foundation design tokens. */
38
+ .bce-avatar--xs { --bce-avatar-size: var(--bc-size-ui-24); --bce-avatar-badge-size: var(--bc-size-ui-8); --bce-avatar-initials-size: var(--bc-type-label-4-font-size); }
39
+ .bce-avatar--sm { --bce-avatar-size: var(--bc-size-ui-32); --bce-avatar-badge-size: var(--bc-size-ui-12); --bce-avatar-initials-size: var(--bc-type-label-4-font-size); }
40
+ /* md is the default and needs no size modifier. */
41
+ .bce-avatar--md { --bce-avatar-size: var(--bc-size-ui-40); --bce-avatar-badge-size: var(--bc-size-ui-12); }
42
+ .bce-avatar--lg { --bce-avatar-size: var(--bc-size-ui-48); --bce-avatar-badge-size: var(--bc-size-ui-16); }
43
+ .bce-avatar--xl { --bce-avatar-size: var(--bc-size-ui-64); --bce-avatar-badge-size: var(--bc-size-ui-16); --bce-avatar-initials-size: var(--bc-type-label-2-font-size); }
44
+ .bce-avatar--2xl { --bce-avatar-size: var(--bc-size-ui-96); --bce-avatar-badge-size: var(--bc-size-ui-24); --bce-avatar-initials-size: var(--bc-type-label-1-font-size); }
45
+ .bce-avatar--bordered .bce-avatar__face { outline: var(--bc-border-width-sm) solid var(--bc-color-border-context-subtle); outline-offset: -1px; }
46
+ .bce-avatar--rounded { --bce-avatar-radius: var(--bc-radius-md); }
47
+ /* Overlay nodes are optional. Presence and verified states must be explicit. */
48
+ .bce-avatar__status, .bce-avatar__verified, .bce-avatar__badge, .bce-avatar__notifications {
49
+ position:absolute; box-sizing:border-box; z-index:1;
50
+ display:none; align-items:center; justify-content:center;
51
+ border: var(--bc-border-width-sm) solid var(--bc-color-surface-context);
52
+ background:var(--bc-color-surface-context);
53
+ }
54
+ .bce-avatar__status {
55
+ right:0; bottom:0; width:var(--bce-avatar-badge-size); height:var(--bce-avatar-badge-size);
56
+ border-radius:var(--bc-radius-full);
57
+ }
58
+ .bce-avatar[data-status="online"] .bce-avatar__status { display:flex; background:var(--bc-color-fill-success); }
59
+ .bce-avatar[data-status="offline"] .bce-avatar__status { display:flex; background:var(--bc-color-fill-neutral); }
60
+ .bce-avatar[data-status="away"] .bce-avatar__status { display:flex; background:var(--bc-color-fill-warning); }
61
+ .bce-avatar[data-status="busy"] .bce-avatar__status { display:flex; background:var(--bc-color-fill-error); }
62
+ .bce-avatar__verified, .bce-avatar__badge { top:0; right:0; width:var(--bce-avatar-badge-size); height:var(--bce-avatar-badge-size); border-radius:var(--bc-radius-full); }
63
+ .bce-avatar[data-verified="true"] .bce-avatar__verified { display:flex; color:var(--bc-color-text-primary-strong-inverse); background:var(--bc-color-fill-primary); }
64
+ .bce-avatar__verified svg { display:block; width:80%; height:80%; fill:none; stroke:currentColor; stroke-width:2.5; stroke-linecap:round; stroke-linejoin:round; }
65
+ .bce-avatar__badge { display:flex; overflow:hidden; }
66
+ .bce-avatar__badge img { width:100%; height:100%; object-fit:cover; }
67
+ .bce-avatar__notifications {
68
+ top:0; left:100%; transform:translate(-35%,-25%); display:flex;
69
+ min-width:var(--bc-size-ui-16); min-height:var(--bc-size-ui-16);
70
+ padding-inline:var(--bc-size-ui-4); border-radius:var(--bc-radius-full);
71
+ color:var(--bc-color-text-error-strong-inverse); background:var(--bc-color-fill-error);
72
+ font-family: var(--bc-type-label-4-font-family); font-weight: var(--bc-type-weight-600); font-size: var(--bc-type-label-4-font-size); line-height: 1; font-variant-numeric:tabular-nums;
73
+ }
74
+ /* Explicit no-count state, rather than silently interpreting text. */
75
+ .bce-avatar__notifications[hidden] { display:none; }
76
+
77
+ /* Logo/icon badge anatomy without inline SVG presentation attributes. */
78
+ .bce-avatar__badge svg { display:block; width:100%; height:100%; }
79
+ .bce-avatar__badge svg rect { fill:var(--bc-color-fill-context); }
80
+ .bce-avatar__badge svg path { fill:none; stroke:var(--bc-color-text-context-inverse); stroke-width:2; }
@@ -0,0 +1,64 @@
1
+ # Avatar
2
+
3
+ category 01 identity Element. A single Avatar shows a person's or organisation's image, initials or fallback icon. It may display *independent* presence, verification, notification and company-badge overlays. Avatar Group and Avatar Label Group belong to category 03 Components, and are intentionally not part of this Element.
4
+
5
+ ## Installation
6
+
7
+ Install `@buffercreations/buffercore` Foundations, then install/select the `avatar` asset through LevelsUI / CLI. This asset's CSS is built to `dist/components/avatar.css`; it is **not** part of the Foundations npm package.
8
+
9
+ ## Basic usage
10
+
11
+ ```html
12
+ <span class="bce-avatar" role="img" aria-label="Alex Morgan">
13
+ <span class="bce-avatar__face">
14
+ <img class="bce-avatar__image" src="/images/alex.jpg" alt="">
15
+ <span class="bce-avatar__fallback" aria-hidden="true">AM</span>
16
+ </span>
17
+ </span>
18
+ ```
19
+
20
+ Use the **named size scale** `xs`, `sm`, `md`, `lg`, `xl`, `2xl`; `md` is the default and requires no modifier. The dimensions are still mapped internally to the canonical Foundation size tokens. The default is circular. Use `bce-avatar--rounded` for rounded square, and `bce-avatar--bordered` for an outline. All dimensions and colours draw from Foundations tokens.
21
+
22
+ ## State versus styling
23
+
24
+ Class modifiers control size, shape and border. Data attributes express semantic state such as `data-status="online"` or `data-verified="true"`. These states only display overlays if the matching child element exists; setting the attribute alone does not invent its markup. The optional `.bce-avatar__notifications` contains real text rather than a CSS pseudo-element's `content`. Do **not** put the notification count in an attribute and display it via CSS `attr()` alone.
25
+
26
+ Presence: `online`, `offline`, `away`, or `busy`. Do not confuse presence with verification. When status indicators appear, give the user an accessible textual equivalent outside any `aria-hidden` icon.
27
+
28
+ ```html
29
+ <span class="bce-avatar" role="img" aria-label="Alex Morgan, online, verified" data-status="online" data-verified="true">
30
+ <span class="bce-avatar__face">
31
+ <span class="bce-avatar__fallback">AM</span>
32
+ </span>
33
+ <span class="bce-avatar__status" aria-hidden="true"></span>
34
+ <span class="bce-avatar__verified" aria-hidden="true"><svg viewBox="0 0 24 24"><path d="m5 12 4 4 10-10"/></svg></span>
35
+ </span>
36
+
37
+ ```
38
+
39
+ For counts, render `<span class="bce-avatar__notifications" aria-label="3 unread notifications">3</span>` (or keep the count in an accessible label on an enclosing control). Format larger values in the consuming application, e.g. `99+`. Hide empty counts by omitting the node or setting `hidden`; the Element doesn't fetch or calculate notification totals.
40
+
41
+ ## Missing and failed images
42
+
43
+ Omit `.bce-avatar__image` to show `.bce-avatar__fallback`. If the image fails to load, set `data-image-error="true"` on the root; the default styles hide the image and reveal the fallback. This requires a consumer-side image error handler, as **CSS alone cannot reliably detect failed images**. For basic static HTML, a simple optional handler is:
44
+
45
+ ```html
46
+ <img class="bce-avatar__image" src="/avatar.jpg" alt="Alex Morgan"
47
+ onerror="this.closest('.bce-avatar').dataset.imageError='true'">
48
+ ```
49
+
50
+ Use the framework's equivalent error callback in applications instead of inline handlers. The default fallback can be initials or an accessible person-icon SVG; avoid inaccessible blank avatars.
51
+
52
+ ## Optional overlays
53
+
54
+ `__status` appears at bottom-right. `__verified` and `__badge` occupy the top-right position **and should not be used together without a customised layout**; choose which one takes that slot. `__notifications` appears above the upper-right perimeter and may require extra space. This is intentionally documented rather than adding a large set of combination-specific modifier classes.
55
+
56
+ ## Accessibility and behaviour
57
+
58
+ An Avatar is display-only by default. For an avatar that opens a profile, put the Element inside a native `<a>` or `<button>` with an appropriate accessible name, and ensure the surrounding content handles keyboard focus. Avoid duplicated spoken labels: if the Avatar's image is decorative next to the person's name, use `alt=""`. State icons can be `aria-hidden="true"` only if an equivalent accessible name/text is present. All optional overlays are CSS-only; there is no mandatory JavaScript or Behaviour dependency.
59
+
60
+ ## Studio examples and utility-first authoring
61
+
62
+ Each example has two intentional representations: `preview.html` may contain multiple variants for visual comparison, while `code.html` contains **one clean, properly indented, copyable usage example**. Do not place a full variant gallery in Code.
63
+
64
+ The preview wrapper uses Foundation layout utilities (`bc-flex`, `bc-flex-wrap`, `bc-items-center`, `bc-gap-md`), not inline `style` declarations or bespoke wrapper classes. The `bce-avatar` classes exist only for Avatar's own identity presentation, sizes and overlay anatomy, which cannot be produced reliably from a generic utility recipe. Avoid hard-coded SVG colours, inline styles and arbitrary numerical size modifier names.
@@ -0,0 +1,10 @@
1
+ <span class="bce-avatar bce-avatar--xl" data-verified="true" role="img" aria-label="Alex Morgan, verified">
2
+ <span class="bce-avatar__face">
3
+ <span class="bce-avatar__fallback" aria-hidden="true">AM</span>
4
+ </span>
5
+ <span class="bce-avatar__verified" aria-hidden="true">
6
+ <svg viewBox="0 0 24 24" aria-hidden="true">
7
+ <path d="m5 12 4 4 10-10" />
8
+ </svg>
9
+ </span>
10
+ </span>
@@ -0,0 +1,29 @@
1
+ <div class="bc-flex bc-flex-wrap bc-items-center bc-gap-md">
2
+ <span class="bce-avatar bce-avatar--xl" data-verified="true" role="img" aria-label="Alex Morgan, verified">
3
+ <span class="bce-avatar__face">
4
+ <span class="bce-avatar__fallback" aria-hidden="true">AM</span>
5
+ </span>
6
+ <span class="bce-avatar__verified" aria-hidden="true">
7
+ <svg viewBox="0 0 24 24" aria-hidden="true">
8
+ <path d="m5 12 4 4 10-10" />
9
+ </svg>
10
+ </span>
11
+ </span>
12
+ <span class="bce-avatar bce-avatar--xl" role="img" aria-label="Alex Morgan">
13
+ <span class="bce-avatar__face">
14
+ <span class="bce-avatar__fallback" aria-hidden="true">AM</span>
15
+ </span>
16
+ <span class="bce-avatar__notifications" aria-label="3 unread notifications">3</span>
17
+ </span>
18
+ <span class="bce-avatar bce-avatar--xl" role="img" aria-label="Alex Morgan">
19
+ <span class="bce-avatar__face">
20
+ <span class="bce-avatar__fallback" aria-hidden="true">AM</span>
21
+ </span>
22
+ <span class="bce-avatar__badge" aria-hidden="true">
23
+ <svg viewBox="0 0 24 24">
24
+ <rect x="0" y="0" width="24" height="24" rx="12" />
25
+ <path d="M5 18 12 5l7 13" />
26
+ </svg>
27
+ </span>
28
+ </span>
29
+ </div>
@@ -0,0 +1,5 @@
1
+ <span class="bce-avatar bce-avatar--lg" role="img" aria-label="Alex Morgan">
2
+ <span class="bce-avatar__face">
3
+ <span class="bce-avatar__fallback" aria-hidden="true">AM</span>
4
+ </span>
5
+ </span>
@@ -0,0 +1,23 @@
1
+ <div class="bc-flex bc-flex-wrap bc-items-center bc-gap-md">
2
+ <span class="bce-avatar bce-avatar--lg" role="img" aria-label="Alex Morgan">
3
+ <span class="bce-avatar__face">
4
+ <span class="bce-avatar__fallback" aria-hidden="true">AM</span>
5
+ </span>
6
+ </span>
7
+ <span class="bce-avatar bce-avatar--lg" role="img" aria-label="Alex Morgan">
8
+ <span class="bce-avatar__face">
9
+ <span class="bce-avatar__fallback" aria-hidden="true">
10
+ <svg viewBox="0 0 24 24" aria-hidden="true">
11
+ <circle cx="12" cy="8" r="4" />
12
+ <path d="M4 22c0-5 3-8 8-8s8 3 8 8" />
13
+ </svg>
14
+ </span>
15
+ </span>
16
+ </span>
17
+ <span class="bce-avatar bce-avatar--lg" role="img" aria-label="Alex Morgan">
18
+ <span class="bce-avatar__face">
19
+ <img class="bce-avatar__image" src="https://images.unsplash.com/photo-1534528741775-53994a69daeb?w=160&amp;h=160&amp;fit=crop" alt="">
20
+ <span class="bce-avatar__fallback" aria-hidden="true">AM</span>
21
+ </span>
22
+ </span>
23
+ </div>
@@ -0,0 +1,37 @@
1
+ [
2
+ {
3
+ "id": "sizes",
4
+ "title": "Sizes",
5
+ "description": "Named sizes: xs, sm, md, lg, xl and 2xl",
6
+ "preview": "examples/sizes/preview.html",
7
+ "code": "examples/sizes/code.html"
8
+ },
9
+ {
10
+ "id": "fallbacks",
11
+ "title": "Fallbacks",
12
+ "description": "Initials, icon and loaded image",
13
+ "preview": "examples/fallbacks/preview.html",
14
+ "code": "examples/fallbacks/code.html"
15
+ },
16
+ {
17
+ "id": "shapes",
18
+ "title": "Shapes",
19
+ "description": "Circle, rounded and outlined",
20
+ "preview": "examples/shapes/preview.html",
21
+ "code": "examples/shapes/code.html"
22
+ },
23
+ {
24
+ "id": "presence",
25
+ "title": "Presence",
26
+ "description": "Online, offline, away and busy",
27
+ "preview": "examples/presence/preview.html",
28
+ "code": "examples/presence/code.html"
29
+ },
30
+ {
31
+ "id": "badges",
32
+ "title": "Badges",
33
+ "description": "Verified, unread notifications and company logo",
34
+ "preview": "examples/badges/preview.html",
35
+ "code": "examples/badges/code.html"
36
+ }
37
+ ]
@@ -0,0 +1,6 @@
1
+ <span class="bce-avatar bce-avatar--lg" data-status="online" role="img" aria-label="Alex Morgan, online">
2
+ <span class="bce-avatar__face">
3
+ <span class="bce-avatar__fallback" aria-hidden="true">AM</span>
4
+ </span>
5
+ <span class="bce-avatar__status" aria-hidden="true"></span>
6
+ </span>
@@ -0,0 +1,26 @@
1
+ <div class="bc-flex bc-flex-wrap bc-items-center bc-gap-md">
2
+ <span class="bce-avatar bce-avatar--lg" data-status="online" role="img" aria-label="Alex Morgan, online">
3
+ <span class="bce-avatar__face">
4
+ <span class="bce-avatar__fallback" aria-hidden="true">AM</span>
5
+ </span>
6
+ <span class="bce-avatar__status" aria-hidden="true"></span>
7
+ </span>
8
+ <span class="bce-avatar bce-avatar--lg" data-status="offline" role="img" aria-label="Alex Morgan, offline">
9
+ <span class="bce-avatar__face">
10
+ <span class="bce-avatar__fallback" aria-hidden="true">AM</span>
11
+ </span>
12
+ <span class="bce-avatar__status" aria-hidden="true"></span>
13
+ </span>
14
+ <span class="bce-avatar bce-avatar--lg" data-status="away" role="img" aria-label="Alex Morgan, away">
15
+ <span class="bce-avatar__face">
16
+ <span class="bce-avatar__fallback" aria-hidden="true">AM</span>
17
+ </span>
18
+ <span class="bce-avatar__status" aria-hidden="true"></span>
19
+ </span>
20
+ <span class="bce-avatar bce-avatar--lg" data-status="busy" role="img" aria-label="Alex Morgan, busy">
21
+ <span class="bce-avatar__face">
22
+ <span class="bce-avatar__fallback" aria-hidden="true">AM</span>
23
+ </span>
24
+ <span class="bce-avatar__status" aria-hidden="true"></span>
25
+ </span>
26
+ </div>
@@ -0,0 +1,5 @@
1
+ <span class="bce-avatar bce-avatar--lg bce-avatar--rounded" role="img" aria-label="Alex Morgan">
2
+ <span class="bce-avatar__face">
3
+ <span class="bce-avatar__fallback" aria-hidden="true">AM</span>
4
+ </span>
5
+ </span>
@@ -0,0 +1,17 @@
1
+ <div class="bc-flex bc-flex-wrap bc-items-center bc-gap-md">
2
+ <span class="bce-avatar bce-avatar--lg" role="img" aria-label="Alex Morgan">
3
+ <span class="bce-avatar__face">
4
+ <span class="bce-avatar__fallback" aria-hidden="true">AM</span>
5
+ </span>
6
+ </span>
7
+ <span class="bce-avatar bce-avatar--lg bce-avatar--rounded" role="img" aria-label="Alex Morgan">
8
+ <span class="bce-avatar__face">
9
+ <span class="bce-avatar__fallback" aria-hidden="true">AM</span>
10
+ </span>
11
+ </span>
12
+ <span class="bce-avatar bce-avatar--lg bce-avatar--bordered" role="img" aria-label="Alex Morgan">
13
+ <span class="bce-avatar__face">
14
+ <span class="bce-avatar__fallback" aria-hidden="true">AM</span>
15
+ </span>
16
+ </span>
17
+ </div>
@@ -0,0 +1,5 @@
1
+ <span class="bce-avatar bce-avatar--lg" role="img" aria-label="Alex Morgan">
2
+ <span class="bce-avatar__face">
3
+ <span class="bce-avatar__fallback" aria-hidden="true">AM</span>
4
+ </span>
5
+ </span>
@@ -0,0 +1,32 @@
1
+ <div class="bc-flex bc-flex-wrap bc-items-center bc-gap-md">
2
+ <span class="bce-avatar bce-avatar--xs" role="img" aria-label="Alex Morgan">
3
+ <span class="bce-avatar__face">
4
+ <span class="bce-avatar__fallback" aria-hidden="true">AM</span>
5
+ </span>
6
+ </span>
7
+ <span class="bce-avatar bce-avatar--sm" role="img" aria-label="Alex Morgan">
8
+ <span class="bce-avatar__face">
9
+ <span class="bce-avatar__fallback" aria-hidden="true">AM</span>
10
+ </span>
11
+ </span>
12
+ <span class="bce-avatar bce-avatar--md" role="img" aria-label="Alex Morgan">
13
+ <span class="bce-avatar__face">
14
+ <span class="bce-avatar__fallback" aria-hidden="true">AM</span>
15
+ </span>
16
+ </span>
17
+ <span class="bce-avatar bce-avatar--lg" role="img" aria-label="Alex Morgan">
18
+ <span class="bce-avatar__face">
19
+ <span class="bce-avatar__fallback" aria-hidden="true">AM</span>
20
+ </span>
21
+ </span>
22
+ <span class="bce-avatar bce-avatar--xl" role="img" aria-label="Alex Morgan">
23
+ <span class="bce-avatar__face">
24
+ <span class="bce-avatar__fallback" aria-hidden="true">AM</span>
25
+ </span>
26
+ </span>
27
+ <span class="bce-avatar bce-avatar--2xl" role="img" aria-label="Alex Morgan">
28
+ <span class="bce-avatar__face">
29
+ <span class="bce-avatar__fallback" aria-hidden="true">AM</span>
30
+ </span>
31
+ </span>
32
+ </div>
File without changes
@@ -0,0 +1,55 @@
1
+ # Utility-first Layout recipes
2
+
3
+ These use existing BufferCore utilities without new CSS. Stack is registered using kind: recipe and source.html; the remaining examples are copyable compositions. Utility-only recipes can register with docs, examples and direct dependencies, without a className or dummy stylesheet.
4
+
5
+ ## Container
6
+ ```html
7
+ <div class="bc-container">Contained content</div>
8
+ ```
9
+ Alternatives: `bc-container-content`, `bc-container-content-wide`.
10
+
11
+ ## Stack
12
+ ```html
13
+ <div class="bc-flex bc-flex-col bc-gap-md">
14
+ <div>First</div><div>Second</div>
15
+ </div>
16
+ ```
17
+
18
+ ## Inline
19
+ ```html
20
+ <div class="bc-flex bc-flex-row bc-items-center bc-gap-sm">
21
+ <span>One</span><span>Two</span>
22
+ </div>
23
+ ```
24
+
25
+ ## Cluster
26
+ ```html
27
+ <div class="bc-flex bc-flex-wrap bc-items-center bc-gap-sm">
28
+ <span>One</span><span>Two</span><span>Three</span>
29
+ </div>
30
+ ```
31
+
32
+ ## Simple Grid
33
+ ```html
34
+ <div class="bc-grid bc-gap-md">
35
+ <div>First</div><div>Second</div>
36
+ </div>
37
+ ```
38
+ Use `bcl-grid` only if its grid-column behaviour is needed.
39
+
40
+ ## Sticky region
41
+ ```html
42
+ <aside class="bc-sticky bc-top-0">Sticky region</aside>
43
+ ```
44
+ Ensure scroll-container constraints are appropriate.
45
+
46
+ ## Positioning
47
+ ```html
48
+ <div class="bc-relative">
49
+ <div class="bc-absolute bc-inset-0" aria-hidden="true"></div>
50
+ <div class="bc-relative">Foreground content</div>
51
+ </div>
52
+ ```
53
+
54
+ ### Policy
55
+ Prefer utility recipes until an arrangement adds shared constraints, anatomy or responsive logic that utilities cannot convey cleanly. Class prefix for **Layouts** is `bcl-`; `bcc-` belongs only to category 03 Components.
@@ -0,0 +1,46 @@
1
+ {
2
+ "properties": [
3
+ {
4
+ "name": "data-sidebar",
5
+ "type": "expanded | collapsed | hidden",
6
+ "default": "expanded",
7
+ "description": "Visual sidebar track state; application controls changes."
8
+ },
9
+ {
10
+ "name": "--bcl-shell-sidebar-width",
11
+ "type": "CSS length",
12
+ "default": "16rem",
13
+ "description": "Expanded sidebar track width."
14
+ },
15
+ {
16
+ "name": "--bcl-shell-sidebar-collapsed-width",
17
+ "type": "CSS length",
18
+ "default": "4.5rem",
19
+ "description": "Collapsed sidebar track width."
20
+ },
21
+ {
22
+ "name": "--bcl-shell-panel-width",
23
+ "type": "CSS length",
24
+ "default": "18rem",
25
+ "description": "Optional secondary panel width."
26
+ }
27
+ ],
28
+ "anatomy": [
29
+ "bcl-app-shell__header",
30
+ "bcl-app-shell__body",
31
+ "bcl-app-shell__sidebar (optional)",
32
+ "bcl-app-shell__main",
33
+ "bcl-app-shell__panel (optional)"
34
+ ],
35
+ "accessibility": [
36
+ "Keep DOM reading order logical; use native landmark elements for regions.",
37
+ "Layout styling never replaces focus, keyboard or ARIA behaviour."
38
+ ],
39
+ "tags": [
40
+ "layout",
41
+ "application"
42
+ ],
43
+ "notes": [
44
+ "Layout handles expanded/collapsed/hidden widths, but NOT the toggle interaction, storage or mobile drawer behaviour. Application must update data-sidebar and supply accessible controls. The sidebar content must support collapsed presentation explicitly."
45
+ ]
46
+ }
@@ -0,0 +1,25 @@
1
+ {
2
+ "schemaVersion": 1,
3
+ "id": "app-shell",
4
+ "displayName": "App Shell",
5
+ "description": "Full application frame with optional navigation rail, header, main content and an optional secondary panel.",
6
+ "level": "layout",
7
+ "category": [
8
+ "application"
9
+ ],
10
+ "className": "bcl-app-shell",
11
+ "source": {
12
+ "scss": "02. Layouts/application/app-shell/app-shell.scss",
13
+ "css": "dist/components/app-shell.css"
14
+ },
15
+ "dependencies": {
16
+ "css": [
17
+ "foundations"
18
+ ]
19
+ },
20
+ "documentation": {
21
+ "guide": "docs.md",
22
+ "api": "api.json",
23
+ "examples": "examples/index.json"
24
+ }
25
+ }
@@ -0,0 +1,68 @@
1
+ /* BufferCore Level 03 — App Shell. Structural CSS only; colours and spacing use Foundation utilities. */
2
+ .bcl-app-shell {
3
+ --bcl-shell-sidebar-width: 16rem;
4
+ --bcl-shell-sidebar-collapsed-width: 4.5rem;
5
+ --bcl-shell-panel-width: 18rem;
6
+ display: grid;
7
+ grid-template-rows: auto minmax(0, 1fr);
8
+ grid-template-columns: minmax(0, 1fr);
9
+ width: 100%;
10
+ max-width: none;
11
+ min-width: 0;
12
+ min-height: 100vh;
13
+ min-height: 100dvh;
14
+ box-sizing: border-box;
15
+ }
16
+ .bcl-app-shell__header {
17
+ grid-column: 1 / -1;
18
+ grid-row: 1;
19
+ min-width: 0;
20
+ }
21
+ .bcl-app-shell__body {
22
+ grid-column: 1 / -1;
23
+ grid-row: 2;
24
+ display: grid;
25
+ grid-template-columns: minmax(0, 1fr);
26
+ grid-template-areas: "main";
27
+ width: 100%;
28
+ min-width: 0;
29
+ min-height: 0;
30
+ }
31
+ .bcl-app-shell__main { grid-area: main; min-width: 0; min-height: 0; }
32
+ .bcl-app-shell__sidebar { grid-area: sidebar; min-width: 0; min-height: 0; }
33
+ .bcl-app-shell__panel { grid-area: panel; min-width: 0; min-height: 0; }
34
+ .bcl-app-shell[data-sidebar="hidden"] .bcl-app-shell__sidebar { display: none; }
35
+ .bcl-app-shell:not([data-sidebar="hidden"]) .bcl-app-shell__body:has(> .bcl-app-shell__sidebar) {
36
+ grid-template-columns: minmax(0, var(--bcl-shell-sidebar-width)) minmax(0, 1fr);
37
+ grid-template-areas: "sidebar main";
38
+ }
39
+ .bcl-app-shell[data-sidebar="collapsed"] .bcl-app-shell__body:has(> .bcl-app-shell__sidebar) {
40
+ grid-template-columns: minmax(0, var(--bcl-shell-sidebar-collapsed-width)) minmax(0, 1fr);
41
+ }
42
+ .bcl-app-shell .bcl-app-shell__body:has(> .bcl-app-shell__panel) {
43
+ grid-template-columns: minmax(0, 1fr) minmax(0, var(--bcl-shell-panel-width));
44
+ grid-template-areas: "main panel";
45
+ }
46
+ .bcl-app-shell:not([data-sidebar="hidden"]) .bcl-app-shell__body:has(> .bcl-app-shell__sidebar):has(> .bcl-app-shell__panel) {
47
+ grid-template-columns: minmax(0, var(--bcl-shell-sidebar-width)) minmax(0, 1fr) minmax(0, var(--bcl-shell-panel-width));
48
+ grid-template-areas: "sidebar main panel";
49
+ }
50
+ .bcl-app-shell[data-sidebar="collapsed"] .bcl-app-shell__body:has(> .bcl-app-shell__sidebar):has(> .bcl-app-shell__panel) {
51
+ grid-template-columns: minmax(0, var(--bcl-shell-sidebar-collapsed-width)) minmax(0, 1fr) minmax(0, var(--bcl-shell-panel-width));
52
+ }
53
+ @media (max-width: 47.999rem) {
54
+ .bcl-app-shell__body,
55
+ .bcl-app-shell:not([data-sidebar="hidden"]) .bcl-app-shell__body:has(> .bcl-app-shell__sidebar),
56
+ .bcl-app-shell[data-sidebar="collapsed"] .bcl-app-shell__body:has(> .bcl-app-shell__sidebar),
57
+ .bcl-app-shell .bcl-app-shell__body:has(> .bcl-app-shell__panel),
58
+ .bcl-app-shell:not([data-sidebar="hidden"]) .bcl-app-shell__body:has(> .bcl-app-shell__sidebar):has(> .bcl-app-shell__panel),
59
+ .bcl-app-shell[data-sidebar="collapsed"] .bcl-app-shell__body:has(> .bcl-app-shell__sidebar):has(> .bcl-app-shell__panel) {
60
+ grid-template-columns: minmax(0, 1fr);
61
+ grid-template-areas: "sidebar" "main" "panel";
62
+ }
63
+ .bcl-app-shell[data-sidebar="hidden"] .bcl-app-shell__body,
64
+ .bcl-app-shell[data-sidebar="hidden"] .bcl-app-shell__body:has(> .bcl-app-shell__panel) {
65
+ grid-template-columns: minmax(0, 1fr);
66
+ grid-template-areas: "main" "panel";
67
+ }
68
+ }
@@ -0,0 +1,31 @@
1
+ # App Shell
2
+
3
+ A full-width application layout with a header above a flexible body. The body can contain a navigation sidebar, main content and optional secondary panel. It uses **structural CSS** for grid tracks; consumers apply BufferCore Foundation utilities and semantic tokens for colour, spacing, typography and surfaces.
4
+
5
+ ## Grid and sizing
6
+
7
+ - The root fills the width of its parent, with a default viewport-height minimum. To embed in a fixed-height container, override `min-height` on the instance.
8
+ - The header spans the full shell; it is **not** confined to the sidebar width.
9
+ - The main region always uses a flexible `minmax(0, 1fr)` track.
10
+ - Set `data-sidebar="expanded"`, `"collapsed"` or `"hidden"` on the root. The default when absent is expanded.
11
+ - On narrow viewports, regions stack in logical DOM order; this layout does not implement a modal/off-canvas drawer.
12
+ - `--bcl-shell-sidebar-width` (default `16rem`), `--bcl-shell-sidebar-collapsed-width` (`4.5rem`), and `--bcl-shell-panel-width` (`18rem`) control tracks.
13
+ - If there is no sidebar or panel in the DOM, the corresponding region is omitted.
14
+
15
+ ## Usage
16
+
17
+ ```html
18
+ <div class="bcl-app-shell" data-sidebar="expanded">
19
+ <header class="bcl-app-shell__header bc-p-md">Application header</header>
20
+ <div class="bcl-app-shell__body">
21
+ <aside class="bcl-app-shell__sidebar bc-p-md">Navigation</aside>
22
+ <main class="bcl-app-shell__main bc-p-lg">Main application content</main>
23
+ </div>
24
+ </div>
25
+ ```
26
+
27
+ ## Behaviour and accessibility
28
+
29
+ This Layout does **not** create a toggle, persist preferences, hide sidebar labels or provide mobile drawer interactions. Those belong to the application/Behaviour, which must update `data-sidebar` and provide keyboard-accessible controls. Hide or abbreviate sidebar content explicitly in collapsed mode and ensure hidden content is not focusable.
30
+
31
+ Avoid fixing the sidebar with `position: fixed` inside the layout; if a specific application requires sticky navigation, compose that with positioning utilities or a dedicated Behaviour.
@@ -0,0 +1,17 @@
1
+ <div class="bcl-app-shell" data-sidebar="expanded">
2
+ <header class="bcl-app-shell__header bc-p-md">
3
+ <strong>Application header</strong>
4
+ </header>
5
+ <div class="bcl-app-shell__body">
6
+ <aside class="bcl-app-shell__sidebar bc-p-md">
7
+ <strong>Navigation</strong>
8
+ <nav aria-label="Example navigation">
9
+ <p>Overview</p><p>Projects</p><p>Settings</p>
10
+ </nav>
11
+ </aside>
12
+ <main class="bcl-app-shell__main bc-p-lg">
13
+ <h2>Main application content</h2>
14
+ <p>This area expands to fill the remaining width.</p>
15
+ </main>
16
+ </div>
17
+ </div>
@@ -0,0 +1,17 @@
1
+ <div class="bcl-app-shell" data-sidebar="expanded">
2
+ <header class="bcl-app-shell__header bc-p-md">
3
+ <strong>Application header</strong>
4
+ </header>
5
+ <div class="bcl-app-shell__body">
6
+ <aside class="bcl-app-shell__sidebar bc-p-md">
7
+ <strong>Navigation</strong>
8
+ <nav aria-label="Example navigation">
9
+ <p>Overview</p><p>Projects</p><p>Settings</p>
10
+ </nav>
11
+ </aside>
12
+ <main class="bcl-app-shell__main bc-p-lg">
13
+ <h2>Main application content</h2>
14
+ <p>This area expands to fill the remaining width.</p>
15
+ </main>
16
+ </div>
17
+ </div>