Feat: improve File component for accessibility and add more styling options

[jiromaykin]

User story

Open Inwoner (OIP) is using the Den Haag 'File' component. This component could be improved for accessibility and is missing some styling/values. An overview with suggested improvements (as already implemented by OIP itself) can be found in the NLDS discussions here: https://github.com/orgs/nl-design-system/discussions/347#discussioncomment-16208598
This feature request collects the different findings from there.

Describe the solution you'd like

Here is a collection of our findings so that you can choose any of these, or even all of them if this agrees with accessibility research:

design-tokens:

• add a border-radius token, we use rounded borders but there is no design-token for .denhaag-file -> border-radius
• add tokens to style the extension text

HTML/structure

• not making the entire File component a link, since this could be bad for accessibility/screenreaders, OIP made the whole element into a Div, so that only the 'button' like element inside will have its semantic behaviour: https://github.com/maykinmedia/open-inwoner/blob/88630a45eeaeca5fd4ecbe0b074cc9cb226ffb8f/src/open_inwoner/react/components/File/File.tsx#L92 also viewable in OIP Storybook: https://maykinmedia.github.io/open-inwoner/?path=/docs/components-file--docs
• adding some kind of slot so we can use our own Icons (not just SVG)
• OIP currently uses its own logic to either show an 'image/painting' like icon if the file is an image type, or shows a 'document' like icon if it is a type of text file. It is not documented yet in NLDS whether this is a required feature or not.
• add a variant where there is no Download button and no Remove functionality either, since we have a couple of 'preview' situations where no functionality is needed: https://maykinmedia.github.io/open-inwoner/?path=/story/components-file--without-delete-or-link
• add extra spans so that the File extension, and upload-dates can be styled.
• it's better to add javascript like the remove-function if that element is a true HTML Button

CSS/styling

• since the whole File component is a Div here, we needed styling for the Download <a> link, like text-decoration: none; which perhaps could be design-tokens
• set the hard-coded cursor as default if the whole element is no longer a link
• same text-decoration styling was needed for the real 'delete/remove' button, (wither border styling needed to be removed from the Button), but it also needs more styling/design-tokens-as-a-button: https://github.com/maykinmedia/open-inwoner/blob/88630a45eeaeca5fd4ecbe0b074cc9cb226ffb8f/src/open_inwoner/react/components/File/File.scss#L28
• OIP has always displayed the File extensions in all-caps, with its own text-transform: uppercase; style which should perhaps be left outside of the design-tokens.

Describe alternatives you've considered

We are only using the tokens and CSS from Den Haag (so not the React component), and have rebuilt the structure as a Preact/web-component Div ourselves, but still using the same class-names and design-tokens.
If we needed more structure or styling, we added the oip- prefix to these elements.

Additional context

OIP added the Den Haag File component to NLDS Themes repo here: nl-design-system/themes#1353
and added an Utrecht status badge here: nl-design-system/themes#1381

UPDATE: new feedback from accessibility officer April 9th 2026:

"...Voor een screanreadergebruiker is het vooral belangrijk dat alle context aanwezig is op het interactactieve element. Of dan het klikbare gebied vergroot is, of het hele component klikbaar is, maakt an sich niet zo veel uit.

In die van Den Haag mist nu de informatie 'Download' en wordt alleen de bestandsnaam meegegeven. Daarnaast is de tekst Download nog wel bereikbaar met de pijltoetsen (maar niet via de pijltoetsen met een screenreader), dus daar gaat ook iets mis...."

Acceptance criteria

1. When we implement the File component in our project, it needs to have the same border-radius as all our other elements,
2. The 'delete button' behaves like a true button so that screenreaders can detect it as separate from the whole File element and give feedback on its javascript functionality.

[Borai]

@jiromaykin Deze punten klinken allemaal als mooie toevoegingen. Het enige waar ik nog een vraag bij heb is als we de <a> toevoegen aan de knop. Dat we de functionaliteit voor Den Haag overeind houden dat je nog steeds op het gehele component kan klikken om het bestand te downloaden? Als je daar een idee bij hebt hoor ik het graag.

De rest van de punten zijn mij betreft allemaal toevoegingen die het component beter maken. En mogen wat mij betreft doorgevoerd worden.

[jiromaykin]

@Borai Het gehele component visueel klikbaar maken, zou misschien kunnen worden opgelost op dezelfde manier als bij Cards: met een a::before {content: ""; inset: 0px; position: absolute;} zoals hier via devtools inspect: https://nl-design-system.github.io/denhaag/?path=/story/css-cardnews--default
Dit is dan volgens het accessibility idee "...use CSS to expand a link or button's hitbox across the entire surface area of the card"
Dat maakt het dan ook logischer om er nog een Button in te hebben voor (andere) javascript acties waar geen URL voor nodig is.

Ik weet nog niet wat de impact is op de verdere functionaliteit in de DenHaag codebase, zoals het kunnen verwijderen van bestanden, dus: ik zou misschien wel wat individuele issues hieruit kunnen proberen op te lossen met 1 of meerdere Pull Requests, maar nog niet allemaal.
Hebben jullie nog voorkeuren hier in?

[Borai]

Ja ik zie nu dat wij ook een mogelijkheid hebben om te kunnen verwijderen. Hierin wordt een button om het component heen gezet. Maar ik vind jouw oplossing zoals je hier boven omschrijft een mooiere oplossing. Ja van mij mag je een aanzet doen voor verbetering. Als ik ergens bij kan helpen laat maar weten. Je kunt me ook altijd even een berichtje op Slack sturen :)

[jiromaykin]

@Borai dit lijkt toch nog wat extra complex omdat er 3 jaar geleden een Slack discussie over was (https://codefornl.slack.com/archives/C7KDQRXMZ/p1677576902552619), met ongeveer dezelfde vraag, maar toen is besloten om van de hele File 1 link te maken, maar dat is eigenlijk wat achterhaald. Ik ga het voorleggen aan een accessibility expert van het kernteam voordat ik volgende stappen neem.