Wiki source code of Abstract Design System
Last modified by Manuel Leduc on 2026/08/25 10:09
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | See below the exhaustive list of the User Interface (UI) Elements currently supported by the Abstract Design System (ADS). | ||
| 2 | |||
| 3 | All Design System (DS) implementations are expected to comply exhaustively with that definition. | ||
| 4 | |||
| 5 | == Alert == | ||
| 6 | |||
| 7 | {{code language="typescript"}} | ||
| 8 | /** | ||
| 9 | * @since 18.0.0RC1 | ||
| 10 | * @beta | ||
| 11 | */ | ||
| 12 | type AlterAction = { name: string; callback: () => void }; | ||
| 13 | |||
| 14 | /** | ||
| 15 | * @since 18.0.0RC1 | ||
| 16 | * @beta | ||
| 17 | */ | ||
| 18 | type AlertActions = AlterAction[]; | ||
| 19 | |||
| 20 | /** | ||
| 21 | * Props for the alert component. | ||
| 22 | * | ||
| 23 | * @since 18.0.0RC1 | ||
| 24 | * @beta | ||
| 25 | */ | ||
| 26 | type AlertProps = { | ||
| 27 | title?: string; | ||
| 28 | type: "success" | "warning" | "error" | "info"; | ||
| 29 | description?: string; | ||
| 30 | actions?: AlertActions; | ||
| 31 | closable?: boolean; | ||
| 32 | /** | ||
| 33 | * Other (less important) data to show in the alert. | ||
| 34 | * @since 18.0.0RC1 | ||
| 35 | * @beta | ||
| 36 | */ | ||
| 37 | details?: string; | ||
| 38 | /** | ||
| 39 | * Render with flat corners to use as, e.g., a banner. | ||
| 40 | * @since 18.0.0RC1 | ||
| 41 | * @beta | ||
| 42 | */ | ||
| 43 | flatCorners?: boolean; | ||
| 44 | }; | ||
| 45 | {{/code}} | ||
| 46 | |||
| 47 | == Avatar == | ||
| 48 | |||
| 49 | {{code language="typescript"}} | ||
| 50 | /** | ||
| 51 | * Props for the avatar component. | ||
| 52 | * | ||
| 53 | * @since 18.0.0RC1 | ||
| 54 | * @beta | ||
| 55 | */ | ||
| 56 | type AvatarProps = { | ||
| 57 | /** | ||
| 58 | * Image URL. | ||
| 59 | */ | ||
| 60 | image?: string; | ||
| 61 | /** | ||
| 62 | * Image maximum dimension, with a unit (e.g., 30 px) | ||
| 63 | */ | ||
| 64 | size?: string; | ||
| 65 | /** | ||
| 66 | * User name. | ||
| 67 | */ | ||
| 68 | name?: string; | ||
| 69 | }; | ||
| 70 | {{/code}} | ||
| 71 | |||
| 72 | == Breadcrumb == | ||
| 73 | |||
| 74 | {{code language="typescript"}} | ||
| 75 | /** | ||
| 76 | * @since 18.0.0RC1 | ||
| 77 | * @beta | ||
| 78 | */ | ||
| 79 | type BreadcrumbItem = { label: string; url?: string }; | ||
| 80 | |||
| 81 | /** | ||
| 82 | * @since 18.0.0RC1 | ||
| 83 | * @beta | ||
| 84 | */ | ||
| 85 | type BreadcrumbItems = BreadcrumbItem[]; | ||
| 86 | |||
| 87 | /** | ||
| 88 | * Shared types for the x-breadcrumb component implementations. | ||
| 89 | * @since 18.0.0RC1 | ||
| 90 | * @beta | ||
| 91 | */ | ||
| 92 | type BreadcrumbProps = { | ||
| 93 | items: BreadcrumbItems; | ||
| 94 | }; | ||
| 95 | {{/code}} | ||
| 96 | |||
| 97 | == Button (Btn) == | ||
| 98 | |||
| 99 | {{code language="typescript"}} | ||
| 100 | /** | ||
| 101 | * Props for the btn component. | ||
| 102 | * | ||
| 103 | * @since 18.0.0RC1 | ||
| 104 | * @beta | ||
| 105 | */ | ||
| 106 | type BtnProps = { | ||
| 107 | disabled? boolean; | ||
| 108 | variant?: | ||
| 109 | | "default" | ||
| 110 | | "primary" | ||
| 111 | | "success" | ||
| 112 | | "neutral" | ||
| 113 | | "warning" | ||
| 114 | | "danger" | ||
| 115 | | "text"; | ||
| 116 | size?: "small"; | ||
| 117 | pill?: boolean; | ||
| 118 | }; | ||
| 119 | {{/code}} | ||
| 120 | |||
| 121 | == Card == | ||
| 122 | |||
| 123 | {{code language="typescript"}} | ||
| 124 | /** | ||
| 125 | * @since 18.0.0RC1 | ||
| 126 | * @beta | ||
| 127 | */ | ||
| 128 | type CardProps = { | ||
| 129 | title?: string; | ||
| 130 | }; | ||
| 131 | {{/code}} | ||
| 132 | |||
| 133 | == Checkbox == | ||
| 134 | |||
| 135 | {{code language="typescript"}} | ||
| 136 | /** | ||
| 137 | * @since 18.0.0RC1 | ||
| 138 | * @beta | ||
| 139 | */ | ||
| 140 | type CheckboxProps = { | ||
| 141 | label: string; | ||
| 142 | help?: string; | ||
| 143 | modelValue?: boolean; | ||
| 144 | }; | ||
| 145 | {{/code}} | ||
| 146 | |||
| 147 | == Dialog == | ||
| 148 | |||
| 149 | {{code language="typescript"}} | ||
| 150 | /** | ||
| 151 | * @since 18.0.0RC1 | ||
| 152 | * @beta | ||
| 153 | */ | ||
| 154 | type DialogProps = { | ||
| 155 | width?: "auto"; | ||
| 156 | modelValue?: boolean; | ||
| 157 | logo?: string; | ||
| 158 | }; | ||
| 159 | {{/code}} | ||
| 160 | |||
| 161 | {{version since="18.2.0RC1"}} | ||
| 162 | == Dropdown == | ||
| 163 | |||
| 164 | A dropdown is an element with a button and a togglable part. When the button is clicked, the togglable part is toggled. | ||
| 165 | |||
| 166 | {{code language="typescript"}} | ||
| 167 | /** | ||
| 168 | * @since 18.2.0RC1 | ||
| 169 | * @beta | ||
| 170 | */ | ||
| 171 | type DropdownProps = { | ||
| 172 | btnProps?: BtnProps; | ||
| 173 | disabled?: boolean; | ||
| 174 | } | ||
| 175 | {{/code}} | ||
| 176 | {{/version}} | ||
| 177 | |||
| 178 | == FileInput == | ||
| 179 | |||
| 180 | {{code language="typescript"}} | ||
| 181 | /** | ||
| 182 | * @since 18.0.0RC1 | ||
| 183 | * @beta | ||
| 184 | */ | ||
| 185 | type FileInputModel = File | File[] | null | undefined; | ||
| 186 | |||
| 187 | /** | ||
| 188 | * Props for the btn component. | ||
| 189 | * | ||
| 190 | * @since 18.0.0RC1 | ||
| 191 | * @beta | ||
| 192 | */ | ||
| 193 | type FileInputProps = { | ||
| 194 | modelValue: FileInputModel; | ||
| 195 | label: string; | ||
| 196 | }; | ||
| 197 | {{/code}} | ||
| 198 | |||
| 199 | == Form == | ||
| 200 | |||
| 201 | {{code language="typescript"}} | ||
| 202 | /** | ||
| 203 | * Props for the btn component. | ||
| 204 | * | ||
| 205 | * @since 18.0.0RC1 | ||
| 206 | * @beta | ||
| 207 | */ | ||
| 208 | type FormProps = { | ||
| 209 | onFormSubmit?: () => void; | ||
| 210 | }; | ||
| 211 | {{/code}} | ||
| 212 | |||
| 213 | == Img == | ||
| 214 | |||
| 215 | {{code language="typescript"}} | ||
| 216 | /** | ||
| 217 | * @since 18.0.0RC1 | ||
| 218 | * @beta | ||
| 219 | */ | ||
| 220 | type ImgProps = unknown; | ||
| 221 | {{/code}} | ||
| 222 | |||
| 223 | == Load == | ||
| 224 | |||
| 225 | {{code language="typescript"}} | ||
| 226 | /** | ||
| 227 | * @since 18.0.0RC1 | ||
| 228 | * @beta | ||
| 229 | */ | ||
| 230 | type LoadProps = unknown; | ||
| 231 | {{/code}} | ||
| 232 | |||
| 233 | == Menu == | ||
| 234 | |||
| 235 | The menu does not have props but expects to have a combination of ##MenuItem## and ##MenuLabel## in its default slot. | ||
| 236 | |||
| 237 | == MenuItem == | ||
| 238 | |||
| 239 | {{code language="typescript"}} | ||
| 240 | /** | ||
| 241 | * @since 18.0.0RC1 | ||
| 242 | * @beta | ||
| 243 | */ | ||
| 244 | type MenuItemProps = { | ||
| 245 | value: string; | ||
| 246 | /** | ||
| 247 | * @since 18.0.0RC1 | ||
| 248 | * @beta | ||
| 249 | */ | ||
| 250 | disabled?: boolean; | ||
| 251 | }; | ||
| 252 | {{/code}} | ||
| 253 | |||
| 254 | == MenuLabel == | ||
| 255 | |||
| 256 | {{code language="typescript"}} | ||
| 257 | /** | ||
| 258 | * @since 18.0.0RC1 | ||
| 259 | * @beta | ||
| 260 | */ | ||
| 261 | type MenuLabelProps = unknown; | ||
| 262 | {{/code}} | ||
| 263 | |||
| 264 | == Select == | ||
| 265 | |||
| 266 | {{code language="typescript"}} | ||
| 267 | /** | ||
| 268 | * Props of the select component. | ||
| 269 | * @since 18.0.0RC1 | ||
| 270 | * @beta | ||
| 271 | */ | ||
| 272 | type SelectProps = { | ||
| 273 | /** | ||
| 274 | * Label to display. | ||
| 275 | */ | ||
| 276 | label: string; | ||
| 277 | /** | ||
| 278 | * List of items to select from. | ||
| 279 | */ | ||
| 280 | items: Array<string>; | ||
| 281 | /** | ||
| 282 | * Help message. | ||
| 283 | */ | ||
| 284 | help?: string; | ||
| 285 | /** | ||
| 286 | * Whether or not selecting an item from the list is mandatory. | ||
| 287 | * Default: false. | ||
| 288 | */ | ||
| 289 | required?: boolean; | ||
| 290 | /** | ||
| 291 | * The v-model value of the currently selected item. | ||
| 292 | */ | ||
| 293 | modelValue?: string; | ||
| 294 | }; | ||
| 295 | {{/code}} | ||
| 296 | |||
| 297 | == Tab == | ||
| 298 | |||
| 299 | {{code language="typescript"}} | ||
| 300 | /** | ||
| 301 | * Props of the x-tab component. | ||
| 302 | * @since 18.0.0RC1 | ||
| 303 | * @beta | ||
| 304 | */ | ||
| 305 | type TabProps = { | ||
| 306 | tabId: string; | ||
| 307 | }; | ||
| 308 | {{/code}} | ||
| 309 | |||
| 310 | == TabGroup == | ||
| 311 | |||
| 312 | {{code language="typescript"}} | ||
| 313 | /** | ||
| 314 | * @since 18.0.0RC1 | ||
| 315 | * @beta | ||
| 316 | */ | ||
| 317 | type TabGroupProps = { | ||
| 318 | onTabChange: (tabId: string) => void; | ||
| 319 | }; | ||
| 320 | {{/code}} | ||
| 321 | |||
| 322 | == TabPanel == | ||
| 323 | |||
| 324 | {{code language="typescript"}} | ||
| 325 | /** | ||
| 326 | * Props of the x-tab-panel component. | ||
| 327 | * | ||
| 328 | * @since 18.0.0RC1 | ||
| 329 | * @beta | ||
| 330 | */ | ||
| 331 | type TabPanelProps = { | ||
| 332 | tabId: string; | ||
| 333 | }; | ||
| 334 | {{/code}} | ||
| 335 | |||
| 336 | == TextField == | ||
| 337 | |||
| 338 | {{code language="typescript"}} | ||
| 339 | /** | ||
| 340 | * Props of the text-field component. | ||
| 341 | * @since 18.0.0RC1 | ||
| 342 | * @beta | ||
| 343 | */ | ||
| 344 | type TextFieldProps = { | ||
| 345 | name?: string; | ||
| 346 | label: string; | ||
| 347 | required?: boolean; | ||
| 348 | /** | ||
| 349 | * Whether the field should be focused on load or not (default: false). | ||
| 350 | * @since 18.0.0RC1 | ||
| 351 | * @beta | ||
| 352 | */ | ||
| 353 | autofocus?: boolean; | ||
| 354 | modelValue?: string; | ||
| 355 | /** | ||
| 356 | * Help message. | ||
| 357 | * @since 18.0.0RC1 | ||
| 358 | * @beta | ||
| 359 | */ | ||
| 360 | help?: string; | ||
| 361 | /** | ||
| 362 | * Whether the field should be readonly (default: false). | ||
| 363 | * @since 18.0.0RC1 | ||
| 364 | * @beta | ||
| 365 | */ | ||
| 366 | readonly?: boolean; | ||
| 367 | /** | ||
| 368 | * Type of content. | ||
| 369 | * @since 18.0.0RC1 | ||
| 370 | * @beta | ||
| 371 | */ | ||
| 372 | type?: | ||
| 373 | | "date" | ||
| 374 | | "datetime-local" | ||
| 375 | | "email" | ||
| 376 | | "number" | ||
| 377 | | "password" | ||
| 378 | | "search" | ||
| 379 | | "tel" | ||
| 380 | | "text" | ||
| 381 | | "time" | ||
| 382 | | "url"; | ||
| 383 | }; | ||
| 384 | {{/code}} | ||
| 385 | |||
| 386 | == Tree == | ||
| 387 | |||
| 388 | {{code language="typescript"}} | ||
| 389 | import { TreeNode } from '@xwiki/platform-fn-utils'; | ||
| 390 | |||
| 391 | /** | ||
| 392 | * Represents a TreeNode that can be displayed in a Tree component. | ||
| 393 | * @since 18.0.0RC1 | ||
| 394 | * @beta | ||
| 395 | */ | ||
| 396 | type DisplayableTreeNode = TreeNode<{ | ||
| 397 | id: string; | ||
| 398 | label: string; | ||
| 399 | url?: string; | ||
| 400 | activatable?: boolean; | ||
| 401 | }>; | ||
| 402 | |||
| 403 | /** | ||
| 404 | * Props of the Tree component. | ||
| 405 | * @since 18.0.0RC1 | ||
| 406 | * @beta | ||
| 407 | */ | ||
| 408 | type TreeProps<T extends DisplayableTreeNode> = { | ||
| 409 | /** | ||
| 410 | * Node that contains the nodes to display. | ||
| 411 | */ | ||
| 412 | rootNode: T; | ||
| 413 | /** | ||
| 414 | * Whether to display the root node itself (default: false). | ||
| 415 | */ | ||
| 416 | showRootNode?: boolean; | ||
| 417 | /** | ||
| 418 | * Model value that contains the id of the current activated node. | ||
| 419 | */ | ||
| 420 | activated?: string; | ||
| 421 | /** | ||
| 422 | * Model value that contains the ids of the current opened nodes. | ||
| 423 | */ | ||
| 424 | opened?: string[]; | ||
| 425 | /** | ||
| 426 | * Optional method to call when opening a node with empty children. | ||
| 427 | */ | ||
| 428 | lazyLoadChildren?: (node: T) => Promise<void>; | ||
| 429 | /** | ||
| 430 | * Optional method to call when clicking on nodes, replaces the URL click. | ||
| 431 | */ | ||
| 432 | nodeClickAction?: (node: T) => Promise<void>; | ||
| 433 | }; | ||
| 434 | {{/code}} | ||
| 435 | |||
| 436 | == CSS Variables == | ||
| 437 | |||
| 438 | A Design System implementation also declares a set of CSS custom properties. Portable code styles itself with those properties instead of hard-coded values, so it keeps the look and feel of whichever concrete Design System is active. Every implementation declares the properties listed below. An implementation may declare more, and its own page documents those; code using them is no longer portable. | ||
| 439 | |||
| 440 | === Sizes === | ||
| 441 | |||
| 442 | {{code language="none"}} | ||
| 443 | --cr-sizes-max-page-width Width of the main content area. | ||
| 444 | --cr-sizes-main-sidebar-width Default width of the main sidebar. | ||
| 445 | --cr-sizes-main-sidebar-min-width Minimum width of the main sidebar. | ||
| 446 | {{/code}} | ||
| 447 | |||
| 448 | === Base === | ||
| 449 | |||
| 450 | {{code language="none"}} | ||
| 451 | --cr-base-font-size Font size the font size scale is derived from. | ||
| 452 | --cr-base-text-color Color of the text. | ||
| 453 | --cr-base-link-color Color of a link. | ||
| 454 | --cr-base-visited-link-color Color of a visited link. | ||
| 455 | --cr-mute-text-color Color of a de-emphasized text. | ||
| 456 | {{/code}} | ||
| 457 | |||
| 458 | === Typography === | ||
| 459 | |||
| 460 | Three font stacks, a nine step font size scale whose ##medium## step is the base font size, four font weights, and five steps each of letter spacing and line height. | ||
| 461 | |||
| 462 | {{code language="none"}} | ||
| 463 | --cr-font-mono Monospace font stack. | ||
| 464 | --cr-font-sans Sans serif font stack. | ||
| 465 | --cr-font-serif Serif font stack. | ||
| 466 | |||
| 467 | --cr-font-size-2x-small | ||
| 468 | --cr-font-size-x-small | ||
| 469 | --cr-font-size-small | ||
| 470 | --cr-font-size-medium | ||
| 471 | --cr-font-size-large | ||
| 472 | --cr-font-size-x-large | ||
| 473 | --cr-font-size-2x-large | ||
| 474 | --cr-font-size-3x-large | ||
| 475 | --cr-font-size-4x-large | ||
| 476 | |||
| 477 | --cr-font-weight-light | ||
| 478 | --cr-font-weight-normal | ||
| 479 | --cr-font-weight-semibold | ||
| 480 | --cr-font-weight-bold | ||
| 481 | |||
| 482 | --cr-letter-spacing-denser | ||
| 483 | --cr-letter-spacing-dense | ||
| 484 | --cr-letter-spacing-normal | ||
| 485 | --cr-letter-spacing-loose | ||
| 486 | --cr-letter-spacing-looser | ||
| 487 | |||
| 488 | --cr-line-height-denser | ||
| 489 | --cr-line-height-dense | ||
| 490 | --cr-line-height-normal | ||
| 491 | --cr-line-height-loose | ||
| 492 | --cr-line-height-looser | ||
| 493 | {{/code}} | ||
| 494 | |||
| 495 | === Neutral Colors === | ||
| 496 | |||
| 497 | Eleven steps of a neutral ramp, from the lightest to the darkest. | ||
| 498 | |||
| 499 | {{code language="none"}} | ||
| 500 | --cr-color-neutral-50 | ||
| 501 | --cr-color-neutral-100 | ||
| 502 | --cr-color-neutral-200 | ||
| 503 | --cr-color-neutral-300 | ||
| 504 | --cr-color-neutral-400 | ||
| 505 | --cr-color-neutral-500 | ||
| 506 | --cr-color-neutral-600 | ||
| 507 | --cr-color-neutral-700 | ||
| 508 | --cr-color-neutral-800 | ||
| 509 | --cr-color-neutral-900 | ||
| 510 | --cr-color-neutral-950 | ||
| 511 | {{/code}} | ||
| 512 | |||
| 513 | === Border Radii === | ||
| 514 | |||
| 515 | {{code language="none"}} | ||
| 516 | --cr-border-radius-small | ||
| 517 | --cr-border-radius-medium | ||
| 518 | --cr-border-radius-large | ||
| 519 | --cr-border-radius-x-large | ||
| 520 | --cr-border-radius-circle Radius rounding an element into a circle. | ||
| 521 | --cr-border-radius-pill Radius rounding an element into a pill. | ||
| 522 | {{/code}} | ||
| 523 | |||
| 524 | === Spacings === | ||
| 525 | |||
| 526 | Ten steps of a spacing scale, for margins, paddings and gaps. | ||
| 527 | |||
| 528 | {{code language="none"}} | ||
| 529 | --cr-spacing-3x-small | ||
| 530 | --cr-spacing-2x-small | ||
| 531 | --cr-spacing-x-small | ||
| 532 | --cr-spacing-small | ||
| 533 | --cr-spacing-medium | ||
| 534 | --cr-spacing-large | ||
| 535 | --cr-spacing-x-large | ||
| 536 | --cr-spacing-2x-large | ||
| 537 | --cr-spacing-3x-large | ||
| 538 | --cr-spacing-4x-large | ||
| 539 | {{/code}} | ||
| 540 | |||
| 541 | === Input === | ||
| 542 | |||
| 543 | {{code language="none"}} | ||
| 544 | --cr-input-border-color Color of the border of a form field. | ||
| 545 | --cr-input-border-width Width of the border of a form field. | ||
| 546 | {{/code}} |
