Complete and clarify SDC documentation

Also, le'ts remove this misleading section: Does SDC handle contextual links, attributes, title suffix, etc? because:

• Using a PHP Namespace as a prop type is not JSON schema valid and trigger a weird behaviour, so it must be avoided.
• An empty array or an empty object is JSON Schema valid, but a bad practice because it doesn't give any useful information about the expected data. Let's not promote it.

Other idea for documentation update: help people to differentiate props and slots in presenter templates:

In node.html.twig:

• node variable has the data to send to props
• content has the data to send to slots

In user.html.twig:

1. user variable has the data to send to props
2. content has the data to send to slots

...

Hi @dalemoore,

Would you also say that doing this:

attributes:
      type: Drupal\Core\Template\Attribute
      title: 'Attributes'
      description: 'HTML attributes to apply to the component.'

in the component.yml is incorrect?

It is not incorrect in a SDC POV but:

• useless because the attributes variable is automatically injected to the component anyway, so no need to add it to the component definition
• ugly because using PHP namespaces (like Drupal\Core\Template\Attribute) as types is not compliant with JSON Schema and SDC has implemented a quirk to mange them. So let's avoid this

If I try to use the 'only' keyword, like this then I cannot include slots/blocks that aren't explicitly included in the Twig template as blocks.

I ddin't know this about embed, that's one more reason to promote Twig include() function (function, not tag !) (with with_context = false !) instead of the messy embed tag.

If the attributes prop isn't right, then I would ask: how do we add a class, ID, or other attribute to our components from presenter templates? Having to manually add a class prop (or other attribute) onto every SDC seem to be the only way, but and is burdensome.

I would not recommend adding a class prop. attributes prop is already perfect for this and it is not what is causing issue here. attributes also allows to attach other attributes, and is expected by any mechanism adding semantic annotation, SEO tags, styles utilities from design systems, accessibility attributes...

If including an attributes prop, I wonder if it would be better to name it component_attributes instead of just attributes to prevent the leaking of attributes from the presenter template. We already have title_attributes, content_attributes, etc. for other things.

Radix theme did this mistake: #3482516: Inconsistent `attributes` handling Now the have have both COMPONENT_attributes and attributes in some templates, which is confusing and may lead to other issues.

Using the standard attributes prop must be enough and work well.

I downloaded UI Patterns, but there are no SDCs in there as examples

We don't ship SDC component in UI Patterns 2 by design. UI Patterns 2 is only a "bridge" between SDC and other Drupal API.

However, we are currently adding an extensive documentation to UI Patterns 2, expected before Christmas, and I hope it will give you the information you need.

Also, do you have examples of how you're using SDCs?

UI Suite team (the team doing UI Patterns, which I am part of) are also maintaining SDC themes:

• https://git.drupalcode.org/project/ui_suite_bootstrap/-/tree/5.1.x/compo...
• https://git.drupalcode.org/project/ui_suite_daisyui/-/tree/4.0.x/components
• https://git.drupalcode.org/project/ui_suite_dsfr/-/tree/1.1.x/components
• ...

Beware, there are 2 additions from UI Patterns 2 in those components compared to regular SDC components:

• #3390712: Add component variants to SDC has been already implemented
• we use the native JSON schema's $def/$ref mechanism to avoid repeating complex prop schemas

Beside that, you can get inspiration from them.

Also, the tool we are using to check our SDC good practices, https://www.drupal.org/project/sdc_devel, is already usable, but the rules set needs some tweaking (wording, scope, levels...) which will happen around Christmas.

I don't get how I can do slots with include and again, the docs only say use embed with slots.

That's why the doc needs to be updated ;)

A summary (without the only and with_context keywords, for clarity):

My recommendation will be the second one: clear, simple, reliable.

some kind of render array magic, I guess through preprocess functions in your .theme? How else would you use this method?

Most of the time, as the return value of configurable plugins related to display building:

• BlockPluginInterface::build()
• FormatterInterface::viewElements()
• LayoutInterface::build()
• StylePluginBase::render()
• ...

Do we add this information to the SDc documentation too?

Step by step, we are gathering information to update this doc. That's nice

AFAIK everything that was supposed to go with an SDC is supposed to go in the theme in the same folder as the component, or at least done in the theme. But I don't think it's best practice to do any of that in a theme?

The component are stored in a theme (or a module), but can be used outside of this theme (or module). Most of the time, component usage is stored in config entities related to display (block.block, entity view displays, views...). Sometimes in content (fields using ckeditor5 data or layout builder data...). Sometimes in code (custom plugins...)

We may do a documentation session with @mherchel during DrupalCon Atlanta

I am very excited about that. There are many sides of SDC documentation which need to be clarified or completed after 2 years of practice.

Data primitives mapping between the 3 formats we are manipulating:

Maybe adding such a table will be useful in the SDC documentation.

Suggestion from @mlncn about replaces property:

looking to improve the documentation slightly, the general advice should be to copy the entire component subdirectory into your themes components directory and add the replaces line. It's not like it can inherit anything it's a true replacement, yes?

Indeed, the replacement component is still a full component with its Twig template and its YAML definition.

From Enrique Lacoma:

Overriding components in a module, in the doc https://www.drupal.org/docs/develop/theming-drupal/using-single-director... says you can't override a component in a module, but I was able to do it, is the documentation correct or doing the override inside a module can create any issue? thanks

Also, tell something about custom & contrib Twig extensions.

So we are good. I am currently editing the documentation.

Update Quickstart

Add an example without block and with include() as the primary example.

✅ DONE.

Keep the example with block and embed, but add the print node:

{% block chip_content %}
  {{ chip_content }}
{% endblock %}

✅ DONE. Switched to include() function

Update Using your new single-directory component

Keep the mentions of block and embed but move it to the page bottom and update any parts which can make readers believing that "slots == Twig blocks".

✅ DONE.

Also, don't promote the use of include tag at the same level of include function:

✅ DONE.

Render element is already explained in this page, but it can be promoted a bit.

✅ DONE.

It is a good opportunity to explain the difference between presenter templates:

• unavoidable because of the lack of display building: breadcrumbs.html.twig, status-message.html.twig, menu.html.twig, pager.html.twig..
• the ones conflicting with the display building: node.html.twig, field.html.twig, views.html.twig, block.html.twig...

NOT DONE YET

Also, "Component data validation" section can be moved in "Creating a single-directory component" page.

✅ DONE.

Also, le'ts remove this misleading section: Does SDC handle contextual links, attributes, title suffix, etc? because:

• Using a PHP Namespace as a prop type is not JSON schema valid and trigger a weird behaviour, so it must be avoided.
• An empty array or an empty object is JSON Schema valid, but a bad practice because it doesn't give any useful information about the expected data. Let's not promote it.

TODO

Update Creating a single-directory component

The replacement component is still a full component with its Twig template and its YAML definition.

TODO

says you can't override a component in a module, but I was able to do it,

TODO

Data primitives mapping between the 3 formats we are manipulating:

✅ DONE. 2025-05-09

Tell something about custom & contrib Twig extensions.

TOOD

Update What are Props and Slots in Drupal SDC Theming?

Remove any mention of block and embed. The goal of this page is to teach about slots and props, not to list all ways of calling components from templates.

✅ DONE. 2025-05-03

A bit of rewording and an annotated component screenshot like this can also help the reader:

✅ DONE. 2025-05-03

Update API for Single-Directory Components

Replace the example with block and embed by one with include. Or simply remove the example.

✅ DONE.

A schema can be a good way to show how the different parts of the API are interacting.

TODO

Update Frequently Asked Questions

says you can't override a component in a module, but I was able to do it,

TODO

• "What contrib modules are compatible with SDC?" removed because obsolete
• "Does SDC handle attributes, title_suffix, is_admin, etc?" expanded
• "Why some PHP namespaces are used in props schema?" added
• "How can I pass arbitrary HTML into a component?" clarify to avoid confusion between slots & blocks
• Empty chapters were removed
• Add "UI Patterns" link alongside "SDC Display" link
• Add syntax color in YAML

✅ DONE.

Broadly, there are at least two common approaches:

1. Flat component structure with Render API – as promoted by UI Patterns, where HTML is composed by injecting subcomponents and applying styles externally. This approach often uses slots and discourages direct include.

2. Atomic design systems – where components are self-contained and reuse smaller parts through include.

Both approaches look atomic to me :) But let's not spend too much time on terminology.

Both approaches are valid and compatible with SDC. However, the documentation currently frames the first approach as a best practice, which may not suit all projects or design systems.

I am all to describe the 2 approaches in documentation if both are relevant. Can you share with us:

• the characteristics of a Drupal project where the second approach is best?
• an example of a (public) design system where the second approach is best?

In "Slots & props data in a Drupal template", add a full example using both content renderable and typed data from object, into complex SDC props like icons.

https://www.drupal.org/docs/develop/theming-drupal/using-single-director...

Hello Sergey,

The best advice I could share, which works 90% of the time is to model your SDC without thinking about is use in Drupal. Model it to have the best implementation of the target UI component, keep it clean and focus on stateless UI logic, and Drupal integration will follow.

For your specific example:

Create a separate slot for each field and render them individually using content.field_title, content.field_description, content.field_cta, and then use content|without(['field_image', 'field_title', 'field_description', 'field_cta']) to preserve proper cache metadata,

Field values can go to slots or props:

• Field formatters, from the content variable (for example, content.field_cta) go to slots
• Field properties, from the node variable (for node templates) - (for example, node.field_cta.0.text) go to props

So we are talking about slots here. You don't need to have a slot per field. As said before, the slot must match the UI logic we are implementing.
For example, your card component can have header, body and footer slots and then you can map:

• content.field_title to header
• content.field_image and content.field_description to body
• content.field_cta to footer

Does it make sense?