Guidance change to File upload component

package.json

@@ -36,7 +36,7 @@
   "dependencies": {
     "accessible-autocomplete": "^3.0.1",
     "clipboard": "^2.0.11",
-    "govuk-frontend": "^5.8.0",
+    "govuk-frontend": "github:alphagov/govuk-frontend#5740625c2",
     "iframe-resizer": "^4.4.5",
     "lunr": "^2.3.9"
   },

src/accessibility-statement.md

@@ -75,7 +75,7 @@ For the GOV.UK Design System website and the GOV.UK Frontend Documentation websi
 Additional accessibility concerns from the GOV.UK Frontend codebase include:
 
 1.  The details component does not work well with Dragon and older versions of VoiceOver. This is not an issue with our details component, but is a known issue with the assistive technology and the `<details>` HTML element. Track our progress on the [GitHub issue: ‘Details component does not work well with Dragon and VoiceOver’](https://github.com/alphagov/govuk-frontend/issues/3693).
-2.  [A bug within Dragon means no action is taken when trying to activate the file upload component](https://github.com/alphagov/reported-bugs/issues/35) through the command ‘click choose file’ or ‘click button’. This is a usability issue originating from the assistive technology. The team is working on building a bespoke component that will fix this. Track our progress on the [GitHub issue: ‘Upload file component doesn’t respond to ‘click choose file’ due to Dragon / browser bugs’](https://github.com/alphagov/govuk-frontend/issues/3686).
+2.  [A bug within Dragon means no action is taken when trying to activate the file upload component](https://github.com/alphagov/reported-bugs/issues/35) through the command ‘click choose file’ or ‘click button’. This is a usability issue originating from the assistive technology. The team has created a [custom file upload component](/components/file-upload/#using-the-improved-file-upload-component) that fixes this. This component is currently behind a feature flag which needs to be used in order to get the improvements. Track our progress on the [GitHub issue: ‘Upload file component doesn’t respond to ‘click choose file’ due to Dragon / browser bugs’](https://github.com/alphagov/govuk-frontend/issues/3686).
 
 ## Preparation of this accessibility statement
 

src/components/file-upload/enhanced/index.njk

@@ -0,0 +1,15 @@
+---
+title: Enhanced - File upload
+layout: layout-example-form.njk
+---
+
+{% from "govuk/components/file-upload/macro.njk" import govukFileUpload %}
+
+{{ govukFileUpload({
+  id: "file-upload-1",
+  name: "fileUpload1",
+  label: {
+    text: "Upload a file"
+  },
+  javascript: true
+}) }}

src/components/file-upload/index.md

@@ -37,6 +37,8 @@ Help users select and upload a file.
 
 You should only ask users to upload something if it’s critical to the delivery of your service.
 
+We improved the component in February 2025, you will need to [enable the improved File upload component as a new feature](#using-the-improved-file-upload-component).
+
 ## How it works
 
 To upload a file, the user can either:
@@ -108,12 +110,48 @@ For example, ‘You can only select up to 10 files at the same time’.
 
 Say ‘The selected file must use the template’.
 
+## Using the improved File upload component
+
+In February 2025 as part of GOV.UK Frontend 5.9.0, we introduced changes to the File upload component that you can opt into.
+
+The improved component is intended to:
+
+- fix accessibility issues
+- improve the user experience
+- allow the text in the component to be translated
+
+Although, we recommend service teams start using the improved component to improve the experience for users, it is a substantial visual change. To allow teams to migrate at their own pace, the improvements are behind a ‘feature flag’.
+
+{{ example({ group: "components", item: "file-upload", example: "enhanced", html: true, nunjucks: true, open: false, size: "m" }) }}
+
+### Changes in the improved component
+
+To make it easier for users to ‘drag and drop’ files, we’ve made the drop zone:
+
+- bigger
+- visible at all times
+- more visually responsive to user interactions
+
+We’ve also changed the ‘Choose file’ button to be more consistent with the secondary button in the [Button component](/components/button/).
+
+You can change the text on the button and the ‘no file chosen’ message.
+
+All the text in the component can now be translated to match the language the page is in when JavaScript is running.
+
+#### Improvements for assistive technology users
+
+Users of Dragon Naturally Speaking, a speech recognition tool, will now be able to activate the component by saying commands for interacting with [web page controls](https://www.nuance.com/products/help/dragon/dragon-for-pc/enx/professionalgroup/main/Content/Web/working_with_chrome.htm?Highlight=click%20button). This feature currently does not work with native file input from the browser.
+
+However, due to browser security features this will only work in the first instance. If the component needs to be used more than once, users will need to rely on [mouse commands](https://www.nuance.com/products/help/dragon/dragon-for-pc/enx/professionalgroup/main/Content/CommandandControl/using_your_mouse.htm) or [keyboard commands](https://www.nuance.com/products/help/dragon/dragon-for-pc/enx/professionalgroup/main/Content/CommandandControl/using_your_keyboard.htm), just as they would with the native file input.
+
 ## Research on this component
 
-An accessibility audit has shown some users have encountered a problem when using file upload.
+An accessibility audit has shown some users have encountered a problem when using File upload.
 
 ### Known issues and gaps
 
-The file upload component does not show a visual target area when dragging and dropping a file. We do not plan on fixing this at the moment, as the component inherits and uses the browser's default behaviour. We will revisit this issue if we publish a custom file upload component. More detail on the findings can be found in the [GitHub issue: ‘Upload file component has no visual target area when dragging and dropping a file’](https://github.com/alphagov/govuk-frontend/issues/3685).
+The File upload component does not show a visual target area when dragging and dropping a file. The component inherits and uses the browser’s default behaviour. More detail on the findings can be found in the [GitHub issue: ‘Upload file component has no visual target area when dragging and dropping a file’](https://github.com/alphagov/govuk-frontend/issues/3685).
+
+We revisited this issue in February 2025 and have published a [improved File upload component](#using-the-improved-file-upload-component) to improve the accessibility of the component. Although we’re confident the new component is an improvement on the browser’s default behaviour.
 
 Read a blog post about [design tips for helping users upload things](https://designnotes.blog.gov.uk/2017/02/14/some-design-tips-for-uploading-things/).